الانتقال إلى المحتوى الرئيسي
تُصادِق الـ Wave API باستخدام API keys تُرسَل بصفتها Bearer token:

​
أنواع الـ keys

الـ sandbox والإنتاج خاصّيّتان من خصائص المشروع، لا الحساب ولا المؤسّسة. لكلّ مشروع مفاتيح sandbox ومفاتيح production. يبدأ كلّ مشروع جديد في sandbox. وينتقل المشروع إلى الإنتاج عبر مسار Go-Live الخاصّ به في لوحة التحكّم: تقدّم الطلب، ويراجعه مسؤول في Wave، ويُخصّص للمشروع رقم هاتفه الخاصّ، ثمّ تُنشئ Wave مفتاح sk_live_ له. وتبقى المشاريع الأخرى في مؤسّستك كما هي. تبقى مفاتيح الـ sandbox فعّالة بعد Go-Live. بعض الميزات (التسجيلات، الأرقام الافتراضيّة، الطوابير) تتطلّب مفتاح إنتاج.

​
الحصول على key

تُنشأ الـ API keys وتُدار في لوحة تحكّم Wave (لا عبر الـ API):
  1. سجّل الدخول في wave.sa.
  2. افتح API Keys.
  3. انسخ الـ key عند الإنشاء — يُعرَض مرّة واحدة.
لتدوير الـ key، استخدم Revoke & Regenerate في لوحة التحكّم. يتوقّف الـ key القديم عن العمل فورًا ويُصدَر آخر جديد بصورة ذرّيّة (atomically).

​
النطاقات (Scopes)

يحمل كلّ key نطاقات تحدّد ما يستطيع فعله. اضبطها عند إنشاء الـ key أو تعديله في لوحة التحكّم. يُعيد الطلب لشيء خارج نطاقات الـ key رمز 403 INSUFFICIENT_PERMISSIONS.

​
سجلّ التدقيق

يعرض GET /v1/audit-logs التغييرات في مشروعك، الأحدث أوّلًا: إنشاء الـ keys وتعديلها، والـ Webhooks، والأرقام، وخطوات الانتقال إلى الإنتاج (Go-Live). هو للقراءة فقط ويتطلّب النطاق audit:read. يحصل الـ API key على سجلّات مشروعه فقط. تحصل الـ keys التي يُنشئها المالك أو المسؤول أو المدقّق من صفحة الـ Keys على audit:read افتراضيًّا. لا يستطيع المطوّر منح key النطاق audit:read. لا تحصل الـ keys التي تُنشئها Wave لك (عند التسجيل، وعند إنشاء مشروع، وعند الانتقال إلى الإنتاج) على audit:read. يحصل الـ key الذي لا يحمله على 403 INSUFFICIENT_PERMISSIONS. في البوابة، لا يمكنك كشف key إلا إذا كان دورك يستطيع منح كل النطاقات التي يحملها. مثلًا، لا يستطيع المطوّر كشف key يحمل audit:read، ولا يستطيع المدقّق كشف key يستطيع إجراء تغييرات. في البوابة، يرى العضو الذي دوره في المؤسّسة مالك أو مسؤول أو مدقّق أيضًا تغييرات مستوى المؤسّسة (الأعضاء والفوترة وتسجيلات الدخول).
  • المرشّحات: from وto (بصيغة ISO 8601، شاملة)، وaction وresource وresource_id (تطابق تامّ).
  • الصفحات: limit (من 1 إلى 100، الافتراضيّ 20). أرسل next_cursor في cursor للصفحة التالية؛ قيمته null في الصفحة الأخيرة.
  • من أجرى التغيير: قيمة actor هي user (عضو؛ ويُضبط user_id) أو system (Wave) أو wave_operator (موظّف تشغيل في Wave). لا يعرض إدخال wave_operator هويّة الموظّف ولا عنوان IP.
  • البيئات: يحصل key الـ sandbox وkey الإنتاج للمشروع نفسه على الإدخالات نفسها.
راجع مرجع الـ API للاستجابة الكاملة.

​
إرسال الـ key

يجب أن يتضمّن كلّ طلب الـ Authorization header. تُعيد الطلبات التي تخلو من key صالح 401 مع غلاف الخطأ القياسيّ.
احتفظ بالـ keys على خادمك وخارج نظام التحكّم بالمصادر. الاستثناء الوحيد هو الاتّصال عبر الويب: تستخدم الـ SDK في المتصفّح مفتاح webrtc:write يقيّده Wave بالأصل — اقصر ذلك المفتاح على webrtc:write فقط وأضِفه للأصول التي تتحكّم بها فقط.