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

# إعداد المصادقة عبر API في Didit

> فعّل طرق تسجيل الدخول والإعدادات والعلامة التجارية والحماية من كودك عبر تفويض يعتمده المالك أو مفتاح API خاص بالمصادقة في Didit.

يتيح لك Didit Authentication تفعيل طرق تسجيل الدخول وقراءة إعدادات تطبيقك عبر API. استخدم تفويضاً معتمداً من المالك أو مفتاح API مُسمّى يحمل النطاق `authentication`.

> [!WARNING]
>
> Authentication ميزة جديدة. فعّل الطريقة أولاً في تطبيق في البيئة التجريبية، ثم في تطبيقك في بيئة الإنتاج.

تُرسل كل استدعاءات API الواردة أدناه إلى واجهة إدارة Authentication الخاصة بتطبيقك. عنوان `MANAGEMENT_BASE` هو:

```text theme={null}
https://apx.didit.me/auth/v2/organizations/{org_id}/applications/{application_id}/authentication/
```

تصف `openapi-authentication.json` المسارات نفسها ضمن الوسم `Setup`، وتعتمد عليه حزم SDK للخوادم في توليد نسخها.

## أي بيانات اعتماد تستخدم

يعمل أيٌّ من بيانات الاعتماد الثلاثة، وتقتصر كل منها على ما وافق عليه مالكها.

| بيانات الاعتماد | طريقة الإرسال | ما الذي يمكنها فعله |
| - | - | - |
| مفتاح API مُسمّى بنطاق `authentication` | `x-api-key: <key>` | يُعدّ تطبيقه الخاص ويقرأ إعداداته. المفتاح الذي يحمل `read` يقرأ الإعداد فقط، أما `write` فيقرأ الإعداد ويغيّره. |
| تفويض وافق عليه المالك مع `didit:management` | `Authorization: Bearer <access_token>` | يُعدّ تطبيقات المؤسسات التي وافقت عليها في الموافقة، ضمن دور الشخص. |
| جلسة وحدة التحكم | `Authorization: Bearer <console session token>` | يقرأ الإعدادات أو يغيّرها بحسب عضوية الشخص في المؤسسة ودوره. تتطلب طرق عرض المستخدم النهائي أيضاً جلسة وحدة التحكم والأذونات المناسبة. |

تُرفض بيانات الاعتماد هذه برمز الحالة `403` في كل مسار من مسارات الإعداد، بغض النظر عما يطلبه الطلب من إجراء:

* **السر الأساسي** للتطبيق.
* token من `POST /programmatic/login`، ويُصدر للتطبيق لا للوحة التحكم.
* مفتاح **بدون** نطاق `authentication`، بما في ذلك المفتاح الذي أُنشئ بأعلى مستوى لكل مورد: هذه المفاتيح تظهر بوصفها وصولاً كاملاً، وتبقى الحقول `scopes` فارغة، ولا تُقبل في هذه المسارات.
* مفتاح يتبع **تطبيقاً آخر**، وتفويض مقتصر على `didit:verification`، وتفويض معتمد لمؤسسة أخرى.

يُرجع الطلب الذي لا يحمل أي بيانات اعتماد الرمز `401`. ويبقى لكل تفويض أو مفتاح حدوده الخاصة فوق ذلك: التفويض يحتفظ بنطاقاته والمؤسسات ودور الشخص، والمفتاح يحتفظ بنطاقاته وقائمة السماح لعناوين IP وتاريخ انتهاء صلاحيته.

## الموافقة على الوصول

### باستخدام مفتاح API مُسمّى

افتح **Developers -> API keys** في [Business Console](https://business.didit.me) وأنشئ مفتاحًا للتطبيق الذي تقوم بإعداده. امنحه مورد `authentication` بصلاحية **read** أو **write**: تغطي صلاحية read كل استدعاء يقرأ الإعداد (`GET`)، وتغطي صلاحية write كل استدعاء يغيّر الإعداد (`POST` و`PUT` و`PATCH` و`DELETE`) ويقرؤه أيضًا. راجع [مفاتيح API](https://docs.didit.me/ar/console/api-keys.md) للاطلاع على انتهاء الصلاحية وقوائم السماح لعناوين IP وتدوير المفاتيح؛ يتبع المفتاح تطبيقًا واحدًا ولا يعمل إلا معه.

### عبر اتصال MCP

يستخدم الوكيل المتصل بخادم Didit MCP الإذنَ الذي وافق عليه مالكه في شاشة الموافقة، مع `didit:management`. راجع [مصادقة MCP](https://docs.didit.me/ar/integration/mcp/authentication.md#تسجيل-الدخول-باستخدام-didit).

### لمالك بدون كلمة مرور

تتيح منحة رمز الجهاز ([RFC 8628](https://datatracker.ietf.org/doc/html/rfc8628)) لمالكٍ يسجّل الدخول عبر Google أو مفتاح المرور أو رمز يُرسل إلى بريده الإلكتروني أن يوافق على الوصول نفسه من أي متصفح، دون كتابة كلمة مرور. راجع [تسجيل الدخول بدون متصفح](https://docs.didit.me/ar/integration/mcp/authentication.md#تسجيل-الدخول-بدون-متصفح-رمز-الجهاز).

## تفعيل رمز البريد الإلكتروني

يقبل `PUT methods/{name}/` الحقل `enabled` فقط، ولا شيء غيره بالنسبة إلى طريقة لا تتطلب بيانات اعتماد.

```bash theme={null}
curl --fail-with-body --request PUT "${MANAGEMENT_BASE}methods/code/" \
  -H "x-api-key: $DIDIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true}'
```

يعيد الطلب حالة الطريقة كما هي الآن:

```json theme={null}
{"name": "code", "enabled": true}
```

عند قراءة الإعدادات، يتضمن الإدخال الخاص برمز البريد الإلكتروني `credential_source: null`. أما الطرق المفعّلة دائمًا فلا يمكن إيقافها، إذ يرد هذا الطلب بـ `{"enabled": "always_on"}`.

## تفعيل Google

تأخذ طريقة المصادقة الاجتماعية بيانات اعتماد تطبيق OAuth الخاص بك، أو تطبيق الاختبار من Didit في تطبيق في البيئة التجريبية.

### باستخدام تطبيق Google الخاص بك

```bash theme={null}
curl --fail-with-body --request PUT "${MANAGEMENT_BASE}methods/google/" \
  -H "x-api-key: $DIDIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true, "credentials": {"client_id": "1234.apps.googleusercontent.com", "client_secret": "GOCSPX-..."}}'
```

سجّل `callback_uri` الذي تعيده الاستجابة لدى مزود الخدمة. السر للكتابة فقط: لا تعيده أي استجابة، ولا يمكن استرجاع سوى `client_id`. إذا فعّلت طريقة دون بيانات اعتماد، وكانت لا تملك أي بيانات محفوظة من قبل، فستجيب بـ `{"credentials": "required"}`.

### باستخدام تطبيق الاختبار من Didit (`didit_test`)

يمكن لتطبيق في **البيئة التجريبية** أن يستخدم تطبيقات Didit الاجتماعية بدلًا من تطبيقاتك، وهذا يكفي لإكمال الإعداد والتحقق من أنه يعمل:

```bash theme={null}
curl --fail-with-body --request PUT "${MANAGEMENT_BASE}methods/google/" \
  -H "x-api-key: $DIDIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true, "credential_source": "didit_test"}'
```

يشمل `didit_test` مزودي **Google وMicrosoft وApple وGitHub**، في التطبيقات التجريبية فقط:

| الإجابة | متى |
| - | - |
| `{"credential_source": "sandbox_only"}` | التطبيق في بيئة الإنتاج. لا توفّر تطبيقات الاختبار تسجيل الدخول في بيئة الإنتاج أبدًا. |
| `{"credential_source": "unavailable"}` | لا يملك النشر تطبيق اختبار لذلك المزود، فتبقى الطريقة متوقفة. |
| `200` مع `configured: true` | يوفّر تطبيق الاختبار الطريقة، وتعرضها صفحة تسجيل الدخول المستضافة. |

يُسمّي طلب `GET` على الإعدادات المزودين الذين يمكن لتطبيق الاختبار خدمتهم لهذا التطبيق في `didit_test_credentials`، وتكون قيمته `false` لجميع المزودين الأربعة في تطبيق في بيئة الإنتاج.

## قراءة الإعداد

`GET` على `MANAGEMENT_BASE` هو طلب القراءة للإعداد: كل طريقة مع `enabled` و`credential_source`، إضافةً إلى روابط الاستدعاء وقواعد الجلسة وسياسة التسجيل.

```bash theme={null}
curl --fail-with-body "$MANAGEMENT_BASE" -H "x-api-key: $DIDIT_API_KEY"
```

```json theme={null}
{
  "enabled": true,
  "methods": [
    {"name": "code", "enabled": true, "credential_source": null},
    {"name": "google", "enabled": true, "credential_source": "didit_test", "configured": true, "client_id": "didit-test-google"},
    {"name": "password", "enabled": false, "credential_source": null}
  ],
  "didit_test_credentials": {"google": true, "microsoft": true, "apple": true, "github": true},
  "redirect_uris": ["https://app.example.com/auth/callback"]
}
```

تُدرج الطرق المعطّلة أيضًا، لذا يكفي طلب `GET` واحد لمعرفة ما هو مفعّل وما هو غير مفعّل. تكون قيمة `enabled` في أعلى الاستجابة `false` عندما تكون المصادقة معطّلة للتطبيق. أي تغيير في الإعداد يُجرى بمنحة إدارة أو بمفتاح مسمّى يُرجع الخطأ `409` مع `{"detail": "product_disabled"}`، ولا يُحفظ أي شيء. لا يُفعّل أي استدعاء للإعداد المصادقة، إذ يقوم شخص بتفعيلها للتطبيق من وحدة التحكم، وتعمل استدعاءاتك بعد ذلك.

## باقي الإعداد

| المسار ضمن `MANAGEMENT_BASE` | الطرق | ما يحتويه |
| - | - | - |
| `settings/` | `GET`, `PATCH` | وصول الوكلاء، والمؤسسات، وسياسة المصادقة متعددة العوامل، ودور العضو الافتراضي، وأحداث webhook المعطّلة |
| `onboarding/` | `GET`, `PATCH` | خطوات الإعداد المكتملة، وهل يسجّل الأشخاص الدخول من الصفحة المستضافة أم من شاشاتك الخاصة |
| `branding/` | `GET`, `PATCH` | نصوص الصفحات المستضافة والروابط القانونية (الشعار والألوان مصدرهما التخصيص) |
| `protection/` | `GET`, `PATCH` | سياسات الحماية من الروبوتات ([الحماية من الروبوتات](https://docs.didit.me/ar/authentication/bot-protection.md)) |
| `verified/` | `GET`, `PATCH` | مستوى التحقق عند التسجيل، وقواعد رفع مستوى التحقق، وادعاءات token |
| `emails/`, `emails/{key}/` | `GET` | رسائل تسجيل الدخول الإلكترونية التي يرسلها هذا التطبيق، ومعاينة معروضة لها |
| `domain/` | `GET`, `PUT`, `DELETE` | المصدر المستضاف ونطاق تسجيل الدخول المخصص |
| `domain/verify/`, `domain/activate/` | `POST` | التحقق من DNS الخاص بالنطاق وشهادته، ثم جعله المصدر المعتمد |
| `native-apps/` | `GET`, `PUT` | تطبيقا iOS وAndroid اللذان يشاركان مفاتيح المرور الخاصة بالتطبيق |

يتيح التفويض أو المفتاح الوصول إلى الإعداد وعدّاداته فقط، ولا يتيح أبداً الوصول إلى بيانات المستخدم النهائي: المسارات `users/` و`sessions/` و`sign-ins/` و`overview/`، والمؤسسات العميلة، والأدوار، والاستيراد، وجلسات الوكلاء، ورسائل البريد الإلكتروني التجريبية ما زالت تتطلب جلسة في وحدة التحكم.

ينطبق الإعداد `agent_humans_only` على التطبيق بأكمله. لا يمكن تغييره إلا من مالك المؤسسة أو مسؤولها. يتلقى المفتاح المسمّى الاستجابة `403 owner_or_admin_required`. يتطلب تفعيل الإعداد أيضاً وجود مفتاح مرور مسجَّل (`passkey_required`).

## الأخطاء

| الاستجابة | المعنى |
| - | - |
| `401` | لا توجد بيانات اعتماد. |
| `403` | بيانات اعتماد لا تملك صلاحية إعداد هذا التطبيق، أو ينطبق أحد قيودها الخاصة: `ip_not_allowed`، أو مفتاح منتهي الصلاحية، أو مفتاح للقراءة فقط عند استخدام مسار للكتابة. |
| `409 {"detail": "product_disabled"}` | المصادقة متوقفة للتطبيق، لذلك يُرفض أي تغيير في الإعداد يُجرى بمنح وصول أو بمفتاح. يفعّلها شخص من وحدة التحكم. |
| `400 {"<field>": "<code>"}` | `sandbox_only`، `unavailable`، `not_supported`، `required`، `always_on`، `method_unavailable`، `unknown_field`. |
| `404` | تعذّر العثور على المورد المطلوب. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.