> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# مصادقة طلبات Orbit API باستخدام المفاتيح والرموز المميزة

> مصادقة طلبات Orbit API باستخدام مفاتيح API للاستدعاءات من خادم إلى خادم أو رموز Bearer للجلسات، بالإضافة إلى SAML SSO لمستخدمي لوحة التحكم في المؤسسات.

# المصادقة

تقوم Orbit بمصادقة **طلبات API** بطريقتين: مفتاح API للاستدعاءات من خادم إلى
خادم، ورمز Bearer للجلسة لمستخدمي لوحة التحكم. يمكن للمؤسسات الكبرى أيضًا
تسجيل دخول المستخدمين عبر [تسجيل الدخول الموحد SAML](#single-sign-on-saml)
وتوفيرهم عبر [SCIM](#directory-provisioning-scim). اختر الطريقة التي تتناسب
مع كيفية إجراء الطلب.

## مفتاح API (من خادم إلى خادم)

أدرج مفتاح API الخاص بك في الترويسة `X-API-Key`:

```bash theme={null}
curl https://api.orbit.devotel.io/api/v1/messages \
  -H "X-API-Key: dv_live_sk_your_key_here"
```

## رمز Bearer (مستخدمو لوحة التحكم)

لمستخدمي لوحة التحكم، استخدم رموز JWT Bearer:

```bash theme={null}
curl https://api.orbit.devotel.io/api/v1/messages \
  -H "Authorization: Bearer eyJhbG..."
```

<Note>
  يمكنك أيضًا تمرير مفتاح API عبر `Authorization: Bearer dv_live_pk_...` (أي
  مفتاح `dv_` — `dv_live_sk_` أو `dv_test_sk_` أو `dv_live_pk_` أو `dv_test_pk_`)
  للبيئات التي يتم فيها حظر الترويسة المخصصة `X-API-Key` بواسطة CORS. يقبل
  الخادم كلا الشكلين: يقرأ `X-API-Key` أولاً، ثم يعود إلى رمز `Bearer` يحمل
  بادئة `dv_`. لا يزال JWT (الذي يبدأ بـ `eyJ`) يُعامَل كرمز جلسة للوحة التحكم،
  لذا لا يتعارض الاثنان أبدًا.
</Note>

## تنسيق مفتاح API

| النوع         | البادئة       | الاستخدام                                  |
| ------------- | ------------- | ------------------------------------------ |
| سرية مباشرة   | `dv_live_sk_` | استدعاءات API من جهة الخادم                |
| سرية اختبارية | `dv_test_sk_` | استدعاءات API من جهة الخادم (وضع الاختبار) |
| عامة مباشرة   | `dv_live_pk_` | من جهة العميل (حزم SDK للمتصفح)            |
| عامة اختبارية | `dv_test_pk_` | من جهة العميل (وضع الاختبار)               |

<Warning>
  المفتاح العام (`dv_live_pk_` / `dv_test_pk_`) مخصص للتضمين في التعليمات
  البرمجية من جهة العميل، لذا فهو **مقيد بنطاقات القراءة فقط** عند الإنشاء.
  تُرفض نطاقات الكتابة والإدارة — `messages:write` و`contacts:write` و`admin`
  والحرف البدل `*` وقراءات الحساب الحساسة `billing:read` / `settings:read` —
  للمفتاح العام بخطأ `422`. استخدم **مفتاح سري** (`dv_live_sk_`) لأي عملية
  ترسل البيانات أو تعدلها.

  ومع ذلك، تعامل مع أي مفتاح ترسله إلى المتصفح أو حزمة الجوال على أنه مرئي
  للجمهور وقيده بالحد الأدنى من القراءات التي يحتاجها.
</Warning>

## تسجيل الدخول الموحد (SAML)

يمكن للمؤسسات الكبرى تسجيل دخول مستخدمي لوحة التحكم عبر مزود هوية SAML 2.0 —
Okta وMicrosoft Entra ID (المعروف سابقًا بـ Azure AD) وOneLogin وGoogle
Workspace أو PingFederate. تقوم SSO بمصادقة الأشخاص في لوحة التحكم؛ فهي لا
تنشئ مفاتيح API، لذا لا تزال الاستدعاءات من خادم إلى خادم تستخدم الطرق
المذكورة أعلاه.

يقوم المالك بتكوين الاتصال ضمن **الإعدادات ← تسجيل الدخول الموحد** في لوحة
التحكم (أو عبر `PATCH /api/v1/settings/saml`): قم بتعيين SSO URL الخاص بـ
IdP ومعرف الكيان وشهادة التوقيع، ثم استخدم **اختبار الاتصال** قبل تفعيله.

تحصل كل مؤسسة على مجموعتها الخاصة من نقاط النهاية، والمُعَرَّفة باسم
slug مؤسستك (`orgSlug`). توجد في جذر API، **وليست** ضمن `/api/v1`:

| الطريقة | نقطة النهاية                    | الغرض                                                               |
| ------- | ------------------------------- | ------------------------------------------------------------------- |
| GET     | `/auth/saml/{orgSlug}/metadata` | بيانات XML الوصفية لمزود الخدمة لاستيرادها إلى IdP الخاص بك         |
| GET     | `/auth/saml/{orgSlug}/login`    | بدء تدفق SSO (يعيد التوجيه إلى IdP الخاص بك)                        |
| POST    | `/auth/saml/{orgSlug}/callback` | خدمة مستهلك التوكيد (ACS) — يرسل IdP الخاص بك الاستجابة الموقعة هنا |
| GET     | `/auth/saml/{orgSlug}/logout`   | بدء تسجيل الخروج الموحد                                             |

وجّه IdP الخاص بك إلى نقطة نهاية البيانات الوصفية، على سبيل المثال
`https://api.orbit.devotel.io/auth/saml/acme/metadata` لمؤسسة `acme`.

## توفير الدليل (SCIM)

قم بتوفير مستخدمي لوحة التحكم وإلغاء توفيرهم تلقائيًا من مزود الهوية الخاص
بك عبر SCIM 2.0. أنشئ رمز توفير ضمن **الإعدادات ← SCIM** (أو عبر
`POST /api/v1/settings/scim/generate-token`) — يُعرض الرمز مرة واحدة فقط،
لذا انسخه إلى IdP الخاص بك فورًا.

يرسل IdP الخاص بك الرمز كبيانات اعتماد Bearer في كل طلب:

```bash theme={null}
curl https://api.orbit.devotel.io/scim/v2/acme/Users \
  -H "Authorization: Bearer <your-scim-token>"
```

تتبع نقاط النهاية مواصفات SCIM 2.0 وتُرجع `application/scim+json`. وهي
مُعَرَّفة باسم slug مؤسستك وتوجد في جذر API، **وليست** ضمن `/api/v1`:

| المورد     | نقاط النهاية                                                                                            |
| ---------- | ------------------------------------------------------------------------------------------------------- |
| المستخدمون | `/scim/v2/{orgSlug}/Users` (قائمة، إنشاء)، `/scim/v2/{orgSlug}/Users/{id}` (إحضار، استبدال، تصحيح، حذف) |
| المجموعات  | `/scim/v2/{orgSlug}/Groups` (قائمة، إنشاء/تحديث)، `/scim/v2/{orgSlug}/Groups/{id}` (إحضار)              |
| الاكتشاف   | `/scim/v2/{orgSlug}/ServiceProviderConfig` و`/ResourceTypes` و`/Schemas`                                |

<Note>
  SAML وSCIM مستقلان: تتحكم SSO في كيفية تسجيل دخول المستخدمين، ويتحكم SCIM
  في المستخدمين الموجودين. يمكنك تفعيل أي منهما بشكل مستقل، على الرغم من أن
  معظم مزودي IdP يقومون بتكوينهما معًا.
</Note>

للاطلاع على دليل التوفير الكامل — إنشاء عنوان URL الأساسي وتعيين الأدوار
وفحوصات سلامة IdP وخطوات Okta / Entra / العميل العام — راجع
[دليل توفير SCIM 2.0](/compliance/scim-provisioning).