> ## 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: تأمين طلبات KYC عبر API

> قم بمصادقة طلبات Didit API باستخدام مفتاح في رأس x-api-key. يعود الرمز 401 لمفتاح خاطئ أو منتهي الصلاحية، و403 لمفتاح مفقود.



تعليمات مصادقة API للمساعد الذكي
        نسخ الموجّه إلى الحافظة



      
      

\<pre>

\````# Goal — authenticate against Didit's REST API

Two hosts, two auth schemes. Never mix them up.

\## Host map

\| Host | Surface | Auth header |
\|---|---|---|
\| `https://verification.didit.me` | Verification API — sessions, workflows, entities, transactions, standalone APIs, lists, webhooks, billing (every `/v3/...` route) | `x-api-key: <DIDIT_API_KEY>` |
\| `https://apx.didit.me` | Account / organization / application management (`/auth/v2/programmatic/...`, `/auth/v2/organizations/...`) | `Authorization: Bearer <JWT access_token>` |

The verification API does **not** use OAuth Bearer tokens. It uses a long-lived API key on the `x-api-key` header. Treat the key as a server-side secret — never ship it to a browser or mobile bundle.

\## How to obtain the api_key (no console UI needed)

\<Warning>
Substitute `you@yourdomain.com` below with a real inbox. The register endpoint sends the verification code synchronously, so reserved test domains (`@example.com`, `@example.org`, `@*.test`, `@*.example`, `@*.invalid`) get refused by mail delivery and the call returns a `500`.
\</Warning>

\```bash
\# 1) Register — emails a 6-char code (15 min TTL).
\#    Password rules: ≥8 chars, 1 uppercase, 1 lowercase, 1 digit, 1 special.
curl -X POST https://apx.didit.me/auth/v2/programmatic/register/ \
-H "Content-Type: application/json" \
-d '{"email": "you@yourdomain.com", "password": "StrongP@ss1"}'

\# 2) Verify email — returns api_key inline.
curl -X POST https://apx.didit.me/auth/v2/programmatic/verify-email/ \
-H "Content-Type: application/json" \
-d '{"email": "you@yourdomain.com", "code": "A3K9F2"}'
\# 200 -> { access_token, refresh_token, organization, application: { api_key, client_id, uuid } }
\```

Persist `response.application.api_key` as the env var `DIDIT_API_KEY`.
New keys start with `sk_live_` (live application) or `sk_test_` (sandbox application), followed by 43 URL-safe characters.
Keys created before this format have no prefix and keep working, so never validate a key by its prefix.

\## Recover the key (lost it)

\```bash
\# Log back in to get a fresh JWT
TOK=$(curl -s -X POST https://apx.didit.me/auth/v2/programmatic/login/ \
-H "Content-Type: application/json" \
-d '{"email":"you@yourdomain.com","password":"StrongP@ss1"}' | jq -r .access_token)

\# Find your org and app
curl https://apx.didit.me/auth/v2/organizations/me/ -H "Authorization: Bearer $TOK"
curl https://apx.didit.me/auth/v2/organizations/me/$ORG_ID/applications/$APP_ID/ \
-H "Authorization: Bearer $TOK"
\# Response.api_key is your key.
\```

\## Calling the verification API

\```bash
curl -X POST https://verification.didit.me/v3/session/ \
-H "x-api-key: $DIDIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"workflow_id":"<WORKFLOW_ID>","vendor_data":"user-42","callback":"https://myapp.com/return"}'
\```

\## Failure modes

\| Status | Meaning | Fix |
\|---|---|---|
\| `401` on verification.didit.me | `x-api-key` header wrong, malformed, revoked or expired | Re-fetch via the recover-key flow above, or use a key that has not expired |
\| `403` on verification.didit.me | No `x-api-key` header, a scoped key without access to this resource or action, or a key called from an address outside its IP list | Use a key with that access (Developers -> API keys in the console) |
\| `403` with `"code": "application_deleted"` on verification.didit.me | The key's application was deleted. You get this for a few minutes after the deletion; after that the key is refused like any invalid key | Do not retry: the application and its keys no longer exist. Use a key of an application that exists |
\| `404` on a session route | The session is outside the scoped key's workflows or statuses | Use a key whose limits include that session |
\| `403` on apx.didit.me | JWT `Authorization` header missing or expired | Call `POST /auth/v2/programmatic/login/` again |
\| `429` | Rate limit; response includes a `wait` field (seconds) | Back off, then retry |

\## Sources of truth
\- /openapi-auth.json — every account / org / app endpoint
\- /openapi-25.json — every verification endpoint
\- /integration/integration-prompt — end-to-end integration recipe````

\</pre>



      
      

الصق في

## العثور على مفتاح API الخاص بكفي Didit، تُخصَّص مفاتيح API لـ **تطبيق** محدد داخل حسابك. التطبيق هو مساحة عمل يمكنك من خلالها تكوين مسارات العمل وإدارة عمليات التحقق لمشروع معين أو بيئة محددة.يحصل كل تطبيق على مفتاح API أساسي يتمتع بصلاحية وصول كاملة عند إنشائه. يمكنك إضافة مفاتيح إضافية بجانبه، بحيث يمتلك كل منها فقط صلاحيات الوصول التي تحتاجها خدمة أو شريك معين. للعثور على مفاتيحك:**1. تسجيل الدخول إلى Business Console**انتقل إلى [**Didit Business Console**](https://business.didit.me) وسجّل الدخول.**2. تحديد التطبيق الخاص بك**اختر **التطبيق** الذي تريد العمل معه من القائمة المنسدلة في الأعلى.**3. فتح مفاتيح API**انتقل إلى **المطوّرون -> مفاتيح API** في الشريط الجانبي الأيسر.**4. نسخ مفتاح أو إنشاؤه**المفتاح **الأساسي** هو السر الخاص بالتطبيق نفسه. أنشئ مفتاحاً جديداً لمنح خدمة أو شريك سراً خاصاً به، مع صلاحيات الوصول التي يحتاجها فقط.> [!WARNING]
>
> **مفتاح API الخاص بك هو سر — تعامل معه ككلمة مرور.**
>
> يوفر المفتاح الأساسي وصولاً كاملاً إلى API نيابة عن تطبيقك. لا تكشف عنه أبداً في التعليمات البرمجية للواجهة الأمامية، أو المستودعات العامة، أو حزم جانب العميل. احتفظ به دائماً على جانب الخادم فقط.### تنسيق مفتاح APIتبدأ مفاتيح API الجديدة بـ `sk_live_` لتطبيق بيئة الإنتاج أو `sk_test_` لتطبيق البيئة التجريبية، متبوعة بـ 43 حرفًا آمنًا للاستخدام في عناوين URL (أحرف وأرقام و`-` و`_`).
المفاتيح التي تم إنشاؤها قبل هذا التنسيق لا تحتوي على بادئة وتستمر في العمل دون تغيير.
أرسل المفتاح بالكامل، بما في ذلك البادئة، في الرأس `x-api-key`، ولا ترفض مفتاحاً لمجرد أنه لا يحتوي على بادئة.## العثور على معرّف المؤسسة الخاص بك**معرّف المؤسسة** الخاص بك هو معرّف فريد عالمياً (UUID) يحدد مؤسستك. يمكنك استخدامه في مسارات API المخصصة للمؤسسة مثل `/auth/v2/organizations/me/{org_id}/applications/`. يمكنك نسخه مباشرة من Business Console، دون الحاجة إلى أي استدعاء لـ API:**1. فتح إعدادات المؤسسة**في [**Didit Business Console**](https://business.didit.me), انتقل إلى **إعدادات المؤسسة**.**2. نسخ معرّف المؤسسة**يعرض حقل **معرّف المؤسسة** معرّف UUID الخاص بمؤسستك بجوار اسم المؤسسة، مع زر للنسخ إلى الحافظة.***## إجراء الطلبات الموثقةلمصادقة طلب API، قم بتضمين مفتاح API السري الخاص بك في رأس HTTP المسمى `x-api-key`.فيما يلي مثال على طلب موثق إلى endpoint الخاص بـ `Create Session`:```shell cURL theme={null}
curl --request POST \
     --url https://verification.didit.me/v3/session/ \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'x-api-key: YOUR_API_KEY' \
     --data '
{
  "workflow_id": "WORKFLOW_ID",
  "vendor_data": "USER_ID",
  "callback": "CALLBACK_URL"
}
'
```***## معالجة الأخطاءإذا كان مفتاح API الخاص بك خاطئًا أو مشوّهًا أو أُلغي، فإن API يعيد `401 Unauthorized`:```json theme={null}
{
  "detail": "Authentication credentials were not provided or are invalid."
}
```يعيد API أيضًا `401` للمفتاح المنتهي الصلاحية، مع `"detail": "This API key has expired."`.
يعيد API `403` للطلب الذي لا يحتوي على مفتاح مع `"detail": "You do not have permission to perform this action."`.| رمز الحالة | المعنى |
| - | - |
| **401** | مفتاح API خاطئ، أو مشوّه، أو ملغى، أو منتهي الصلاحية |
| **403** | لم يتم إرسال مفتاح API، أو أن المفتاح لا يمتلك صلاحية الوصول إلى المورد أو الإجراء المطلوب، أو أن الطلب وارد من عنوان خارج قائمة عناوين IP الخاصة بالمفتاح |
| **403** مع `"code": "application_deleted"` | المفتاح ينتمي إلى تطبيق تم حذفه. يعيد API هذه الاستجابة لبضع دقائق بعد الحذف، ثم يرفض المفتاح كأي مفتاح غير صالح. لا تعاود المحاولة: التطبيق ومفاتيحه لم تعد موجودة. |
| **404** | في مسار جلسة: الجلسة خارج نطاق مسارات العمل أو الحالات المحددة للمفتاح |تسرد صفحة [أخطاء API](https://docs.didit.me/ar/integration/api-errors.md) كل حالة ونص استجابة ورمز.***## مفاتيح API محددة النطاقامنح كل خدمة أو شريك مفتاحاً خاصاً به بدلاً من مشاركة المفتاح الأساسي.
يمتلك كل مفتاح صلاحيات وصول خاصة به: بلا وصول، أو قراءة، أو كتابة لكل مورد (الجلسات، والقرارات، والوسائط، والأشخاص، والشركات، والمعاملات، ومسارات العمل، وwebhook، وإعدادات التطبيق، والتحليلات)، وقيود اختيارية لبعض مسارات العمل، أو للجلسات المقبولة فقط، أو لقائمة من عناوين IP، ولتاريخ انتهاء الصلاحية.
يمكنك تدوير مفتاح مع فترة تداخل مدتها 24 ساعة، وإلغاؤه على الفور.تحتفظ المفاتيح التي تم إنشاؤها قبل إتاحة الوصول محدد النطاق بصلاحيات وصول كاملة.راجع [مفاتيح API](https://docs.didit.me/ar/console/api-keys.md) للاطلاع على الإعدادات المسبقة، والموارد التي يغطيها كل منها، وكيفية استجابة API لمفتاح محدد النطاق.> [!TIP]
>
> إذا تلقيت خطأ `401`، فتأكد جيداً من أنك تستخدم مفتاح API الصحيح للتطبيق المناسب وأنه لم تتم إعادة إنشائه.


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