> ## 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. # الحصول على حالة التحقق الإضافي | واجهة Didit للمصادقة > يعرض GET /step-up/{step_up_id}/ حالة التحقق الإضافي وطريقته ومستواه في Didit. نفّذ الإجراء الحساس فقط عند كون الحالة مقبولة. > [!WARNING] > > المصادقة ميزة جديدة. تُقدَّم هذه الـendpoints من قِبل مُصدِر التطبيق الخاص بك، مثل `https://.auth.didit.me`، ولا تقبل مفتاح API الخاص بك لدى Didit أبدًا. تنتمي عملية المصادقة المرحلية (step-up) إلى الجلسة التي أنشأتها، فإذا استخدمت جلسة أخرى رمز الوصول الخاص بها تتلقى الاستجابة `404`. تصبح عملية المصادقة المرحلية في الحالة `pending` بحالة `expired` بعد مرور 30 دقيقة. ## OpenAPI ````yaml ar/openapi-authentication.json GET /step-up/{step_up_id}/ openapi: 3.0.3 info: title: Didit Authentication API version: 1.0.0 description: >- تُعد هذه endpoints المخصصة للخادم لـ Didit Authentication، وهو منتج تسجيل الدخول للمستخدمين النهائيين لتطبيقك. ميزة Authentication **جديدة** وتصل إلى الإنتاج في إصدار 2026-11-01. ## عنوان URL الأساسي كل تطبيق هو جهة إصدار OpenID Connect خاصة به، ويتم تقديم كل endpoint أدناه في المسار الجذري لجهة الإصدار تلك: - `https://.auth.didit.me` لتطبيق في بيئة الإنتاج، أو `https://.sandbox.auth.didit.me` لتطبيق في البيئة التجريبية. - نطاقك المخصص، بمجرد تفعيله. سيحل بعد ذلك محل المضيف الافتراضي كجهة إصدار: تذكره tokens الجديدة في `iss`، وتشير إليه آلية discovery ويتغير المفتاح القابل للنشر. تفشل access tokens الصادرة تحت المضيف الافتراضي في `/session/` و `/step-up/` و `/monitoring-token/` حتى يتم تجديدها. بيئة الإنتاج والبيئة التجريبية هما تطبيقان منفصلان، وبالتالي فهما جهتا إصدار منفصلتان بمفاتيح منفصلة. المفتاح القابل للنشر هو `pk_live_` (للإنتاج) أو `pk_test_` (للبيئة التجريبية) متبوعاً بترميز base64url غير المبطن لجهة الإصدار، دون شرطة مائلة لاحقة: قم بفك ترميزه للعثور على جهة الإصدار. إنه معرّف عام، وليس بيانات اعتماد. يتم أيضاً تقديم نفس endpoints بتنسيق JSON ضمن `https://apx.didit.me/auth/v2/authentication/{application_id}/`. تذكر tokens دائماً جهة الإصدار المذكورة أعلاه، أياً كان العنوان الذي أصدرها. ## بيانات الاعتماد لا تقبل هذه الـ endpoints مطلقاً مفتاح API الخاص بك من Didit أو token لوحة التحكم. - لا تتطلب Discovery و JWKS و `POST /token/` أي بيانات اعتماد. العملاء عامون: لا يوجد سر للعميل (client secret)، ورمز التفويض مرتبط بمتحقق PKCE الخاص به (`S256`). يمثل `client_id` معرّف التطبيق الخاص بك. - تتطلب `/session/` و `/step-up/` و `/monitoring-token/` الـ access token الخاص بالشخص: `Authorization: Bearer `. يُحتسب كل استدعاء ناجح كنشاط في الجلسة، مما يعيد تشغيل مهلة الخمول للجلسة. ## نصوص الطلبات يقبل كل endpoint يتلقى نص طلب كلاً من تنسيقات JSON والترميز كنموذج (form-encoded) ومتعدد الأجزاء (multipart). يسرد هذا المستند تنسيق JSON، بالإضافة إلى form-encoded للطلب `POST /token/` كما يرسله عملاء OAuth. يحصل الحقل الذي لا يقبله الـ endpoint على `400 {"": "unknown_field"}`. ## Tokens - **Access token**: رمز JWT بتشفير ES256 مع الرأس `typ: at+jwt`، صالح لمدة 5 دقائق على الأكثر ولا يتجاوز أبداً مدة جلسته. المطالبات: `AccessTokenClaims`. - **ID token**: رمز JWT بتشفير ES256 مع الرأس `typ: JWT`. المطالبات: `IDTokenClaims`. ولا يُقبل أبداً كـ access token. - **Refresh token**: سلسلة عشوائية يتم تدويرها مع كل استخدام. يؤدي إرسال refresh token مستخدم بالفعل مرة أخرى إلى إبطال الجلسة. تحقق من الـ token باستخدام المفاتيح من `GET /.well-known/jwks.json`: يجب أن تكون الخوارزمية `ES256`، ويجب أن يطابق `typ` نوع الـ token، ويجب أن يساوي `iss` جهة الإصدار التي قمت بتكوينها و `aud` معرّف تطبيقك. لا يكتشف التحقق دون اتصال بالإنترنت الجلسة الملغاة إلا بعد انتهاء صلاحية access token الخاص بها؛ بينما يمثل `GET /session/` التحقق الفوري. ## الأخطاء | نص الاستجابة | الحالة | | --- | --- | | `{"error": ""}` | أخطاء من `POST /token/`، جميعها بالحالة `400`، في بنية نص الاستجابة المحددة في [RFC 6749 section 5.2](https://www.rfc-editor.org/rfc/rfc6749#section-5.2): `invalid_grant` و `invalid_client` و `mfa_required` الخاصة بـ Didit. أخطاء الخدمة: `temporarily_unavailable` و `monitoring_unavailable` و `monitoring_disabled`. | | `{"": [""]}` أو `{"": ""}` | فشل التحقق من صحة أحد حقول الطلب. يشير `non_field_errors` إلى قاعدة تنطبق على عدة حقول، ويشير `unknown_field` إلى حقل لا يقبله الـ endpoint. | | `{"detail": ""}` | `401` (`invalid_token`) و `403` (`origin_not_allowed`) و `404` (تطبيق أو خطوة تصعيد غير معروفة) و `429` (حد المعدل). وأيضاً `400` لنص طلب يتعذر تحليله (`JSON parse error - ...`) و `405` لطريقة لا يدعمها الـ endpoint و `415` لنوع محتوى `Content-Type` غير مدعوم. | يحمل الرمز `401` أيضاً الرأس `WWW-Authenticate: Bearer`، ويحمل الرمز `429` الرأس `Retry-After` بالثواني. هناك حالتا رفض لا تُرجعان بتنسيق JSON. يتم رفض العنوان الذي لا يمثل جهة إصدار قبل وصوله إلى هذه الـ endpoints، على سبيل المثال استجابة `404` فارغة لاسم `*.auth.didit.me` غير مستخدم. ويتلقى معرّف `step_up_id` الذي لا يطابق تنسيق UUID صفحة `404`. ## حدود المعدل يجب أن يمر الطلب عبر طبقتين. **حدود الـ endpoint**، وتُحتسب لكل عنوان IP للعميل، ولكل تطبيق، ولكل endpoint: - Discovery و JWKS: 1,200 طلب في الدقيقة و 12,000 في الساعة. - جميع endpoints الأخرى: 30 طلباً في الدقيقة و 300 في الساعة. يشترك الطلبان `GET` و `DELETE /session/` في عداد واحد. عند تجاوز الحد: `429 {"detail": "Too many requests from this IP address. Please wait before trying again. Expected available in 60 seconds."}`، أو `3600 seconds` للحد الساعي. **الحماية من البوتات**، على كل طلب `POST` و `DELETE`. وتكون مستودعاتها مشتركة بين جميع طلبات `POST` و `DELETE` الخاصة بالتطبيق، بما في ذلك خطوات تسجيل الدخول المستضافة، وتتم إعادة ملئها باستمرار: - 60 طلباً في الدقيقة لكل عنوان IP للعميل. - 30 طلباً في الدقيقة لكل جهاز، للطلبات التي تحدد جهازها، كما تفعل حزم SDK للمتصفح والأجهزة الأصلية. - 3,000 طلب في الدقيقة للتطبيق بالكامل، عبر جميع عناوين IP. وتسحب عمليات تجديد الـ token (`POST /token/` مع `grant_type=refresh_token`) من مستودع خاص بها بدلاً من ذلك: 6,000 في الدقيقة للتطبيق بالكامل. عند تجاوز سعة المستودع: `429 {"detail": "rate_limited Expected available in N seconds."}` (`1 second.` عندما تكون N تساوي 1). يشمل مستودع عنوان IP الواحد عدة endpoints، لذا فإن عنواناً واحداً يجمع بين استدعاءات token و step-up وتسجيل الخروج يمكنه استنزافه قبل الوصول إلى أي حد خاص بالـ endpoint. يحتسب مستودع التطبيق كل عميل للتطبيق، بما في ذلك المتصفحات. تجيب كلتا الطبقتين قبل تشغيل الـ endpoint، لذا فإن الطلب الذي تلقى `429` لم يتم تنفيذه: أعد المحاولة بعد انقضاء `Retry-After`، بما في ذلك طلبات التجديد. ## طلبات المتصفح يجب أن يأتي الطلب الذي يحمل الرأس `Origin` من أحد مصادر التطبيق نفسه أو مصادره المسموح بها، وإلا سيتلقى `403 origin_not_allowed`. لا ترسل الطلبات بين الخوادم الرأس `Origin`. ## ما لا يغطيه هذا المستند تخدم هذه المسارات الصفحات المستضافة، وحزم SDK للمتصفح والأجهزة الأصلية، ووكلاء الذكاء الاصطناعي. وهي ليست جزءاً من عقد الخادم، ولا تستدعيها حزم SDK للخادم: - خطوات تسجيل الدخول: `POST /authorize/` و `POST /password/` و `/email/*` و `/phone/*` و `/password-reset/*` و `/passkeys/*` و `/mfa/*` و `/social/*` و `/protection/complete/`. - الصفحات المستضافة وعمليات الاستدعاء: `/sign-in` و `/magic` و `/invite` و `/reset` و `/verify/` و `/sso/*` و `/wallet/callback/` و `/logo/` وملفات ربط التطبيقات الأصلية تحت `/.well-known/`. - وصول الوكلاء: `/agents/*` و `/grants/`، بما في ذلك `GET /agents/session/`، وهو الفحص المباشر لـ access token الخاص بوكيل الذكاء الاصطناعي. وصول الوكلاء ليس جزءاً من هذا الإصدار من العقد. - واجهة API لإدارة لوحة التحكم الخاصة بـ Authentication، والتي تتطلب جلسات لوحة التحكم. لا يتم تسليم أحداث Authentication كـ webhooks حتى الآن، لذا لا يحدد هذا المستند أي webhook. servers: - url: https://{issuer} description: 'الجهة المصدرة لتطبيقك: مصدر تسجيل الدخول الخاص به.' variables: issuer: default: your-app.auth.didit.me description: >- مضيف الجهة المصدرة: `.auth.didit.me` (بيئة الإنتاج)، أو `.sandbox.auth.didit.me` (البيئة التجريبية)، أو نطاقك المخصص النشط. security: [] tags: - name: Issuer description: مفاتيح الاكتشاف والتوقيع، للتحقق من token. - name: Tokens description: منح رمز التفويض ومنح التحديث. - name: Sessions description: التحقق من الجلسة التابعة لـ token وصول وإنهاؤها. - name: Step-ups description: التحقق قبل إجراء حساس. - name: Monitoring description: بيانات اعتماد الجهاز لأحداث مراقبة المعاملات. paths: /step-up/{step_up_id}/: get: tags: - Step-ups summary: الحصول على إجراء step-up description: >- الحالة الحالية للتحقق الإضافي. استدعه باستخدام token وصول من الجلسة نفسها التي أنشأت التحقق الإضافي، واتخذ إجراءً فقط عندما تكون قيمة `status` هي `approved`. operationId: authentication_retrieve_step_up parameters: - name: step_up_id in: path required: true description: >- معرّف `id` من `POST /step-up/`، وهو أيضاً معامل الاستعلام `step_up` في `return_to` الخاص بك. تؤدي القيمة التي ليست من نوع UUID إلى صفحة `404`، وليس استجابة JSON. schema: type: string format: uuid example: 94efc2c3-ca84-42fe-900b-6fb61669a7a1 responses: '200': description: التحقق الإضافي. headers: Cache-Control: description: 'دائماً `no-store`: لا تقم بتخزين هذه الاستجابة مؤقتاً أبداً.' schema: type: string example: no-store Pragma: description: دائماً `no-cache`. schema: type: string example: no-cache content: application/json: schema: $ref: '#/components/schemas/StepUp' examples: Approved: summary: 'مقبولة: يمكنك المتابعة' value: id: 94efc2c3-ca84-42fe-900b-6fb61669a7a1 rule: payout method: selfie status: approved level: liveness_face_match amount: '900.00' currency: USD created_at: '2026-10-17T10:41:14.894632Z' completed_at: '2026-10-17T10:43:02.118204Z' expires_at: '2026-10-17T11:11:14.894581Z' Pending: summary: لم تنتهِ بعد value: id: 94efc2c3-ca84-42fe-900b-6fb61669a7a1 rule: payout method: selfie status: pending level: null amount: '900.00' currency: USD created_at: '2026-10-17T10:41:14.894632Z' completed_at: null expires_at: '2026-10-17T11:11:14.894581Z' '401': $ref: '#/components/responses/InvalidToken' '403': $ref: '#/components/responses/OriginNotAllowed' '404': description: >- لا توجد عملية تحقق تصعيدي بهذا المعرّف تتبع هذه الجلسة، أو أن التطبيق غير معروف. headers: Cache-Control: description: 'دائماً `no-store`: لا تقم بتخزين هذه الاستجابة مؤقتاً أبداً.' schema: type: string example: no-store Pragma: description: دائماً `no-cache`. schema: type: string example: no-cache content: application/json: schema: $ref: '#/components/schemas/Detail' examples: StepUpNotFound: summary: تحقق إضافي (step-up) غير معروف value: detail: No VerificationCheck matches the given query. '429': $ref: '#/components/responses/RateLimited' '503': $ref: '#/components/responses/TemporarilyUnavailable' security: - AccessToken: [] components: schemas: StepUp: type: object description: عملية تحقق يتعين على الشخص اجتيازها قبل اتخاذ الإجراء. required: - id - rule - method - status - level - amount - currency - created_at - completed_at - expires_at properties: id: type: string format: uuid example: 94efc2c3-ca84-42fe-900b-6fb61669a7a1 rule: type: string enum: - payout - device - bank - contact description: >- القاعدة التي طلبت ذلك. عند انطباق عدة قواعد، يتم اختيار القاعدة ذات الطريقة الأقوى. example: payout method: type: string enum: - liveness - selfie - full_id description: >- ما يقوم به الشخص: `liveness`، أو `selfie` (كشف الحيوية مع مطابقته للوجه الذي بحوزة Didit بالفعل)، أو `full_id` (المستند وصورة سيلفي). عندما لا تحتفظ Didit بأي وجه للشخص بعد، يتحول `selfie` إلى `full_id` بمجرد فتحه لـ `verification_url`. example: selfie status: type: string enum: - pending - review - approved - declined - expired - superseded description: >- اتخذ إجراءً فقط عند `approved`. ينتظر `review` مراجعة فريقك. لا يعد `declined` نهائياً طالما أن `verification_url` يعمل: يمكن للشخص المحاولة مرة أخرى، وتعود خطوة التحقق الإضافي إلى `pending`. يعني `superseded` أن فحصاً آخر قد تولى عملية التحقق الخاصة بها، أو أن النتيجة لم تكن لخطوة التحقق الإضافي هذه: أنشئ خطوة جديدة. example: pending level: type: string nullable: true enum: - liveness - liveness_face_match - full_id - null description: المستوى الذي بلغه التحقق بمجرد قبوله. example: null amount: type: string nullable: true description: مبلغ الدفع، بمنزلتين عشريتين. example: '900.00' currency: type: string nullable: true example: USD created_at: type: string format: date-time example: '2026-10-17T10:41:14.894632Z' completed_at: type: string format: date-time nullable: true example: null expires_at: type: string format: date-time description: >- 30 دقيقة بعد الإنشاء. تؤدي قراءة خطوة التوثيق الإضافي (step-up) أولاً إلى جمع أي نتيجة وصل إليها التحقق، لذا يمكن أن تظل قراءته `approved` أو `review` أو `declined` بعد هذا الوقت؛ وتلك التي لا تزال `pending` تُقرأ `expired`. example: '2026-10-17T11:11:14.894581Z' Detail: type: object required: - detail properties: detail: type: string example: invalid_token OAuthError: title: OAuth error type: object description: خطأ OAuth (القسم 5.2 من RFC 6749) أو خطأ في الخدمة. required: - error properties: error: type: string example: invalid_grant responses: InvalidToken: description: >- إن access token مفقود، أو غير صالح، أو منتهي الصلاحية، أو موقّع من جهة إصدار أو مفتاح آخر، أو هو ID token، أو agent token، أو تم استبداله عبر تحديث؛ أو تم إلغاء جلسته، أو انتهت مهلة خمولها، أو تجاوزت فترة صلاحيتها، أو لم تعد تستوفي سياسة MFA الخاصة بك، أو تم حظر الشخص أو لم يعد بريده الإلكتروني متحققاً منه. وجّه الشخص لإعادة تسجيل الدخول مرة أخرى. headers: WWW-Authenticate: description: '`Bearer`.' schema: type: string example: Bearer Cache-Control: description: 'دائماً `no-store`: لا تقم بتخزين هذه الاستجابة مؤقتاً أبداً.' schema: type: string example: no-store Pragma: description: دائماً `no-cache`. schema: type: string example: no-cache content: application/json: schema: $ref: '#/components/schemas/Detail' examples: InvalidToken: summary: تم رفض token الوصول value: detail: invalid_token OriginNotAllowed: description: >- تضمن الطلب رأس `Origin` ليس خاصاً بالتطبيق ولا يندرج ضمن أصول التطبيق المسموح بها. لا ترسل طلبات الخادم أي `Origin`. headers: Cache-Control: description: 'دائماً `no-store`: لا تقم بتخزين هذه الاستجابة مؤقتاً أبداً.' schema: type: string example: no-store Pragma: description: دائماً `no-cache`. schema: type: string example: no-cache content: application/json: schema: $ref: '#/components/schemas/Detail' examples: OriginNotAllowed: summary: الأصل غير مسموح به value: detail: origin_not_allowed RateLimited: description: >- طلبات كثيرة جداً من عنوان IP هذا لهذا الـ endpoint، أو في حالة `POST` أو `DELETE`، فإن وعاء الحماية من البوتات فارغ. لم يتم تشغيل أي شيء: انتظر عدد الثواني المحدد في `Retry-After`، ثم أعد المحاولة. headers: Retry-After: description: عدد الثواني الواجب انتظارها قبل إعادة المحاولة. schema: type: integer example: 60 Cache-Control: description: 'دائماً `no-store`: لا تقم بتخزين هذه الاستجابة مؤقتاً أبداً.' schema: type: string example: no-store Pragma: description: دائماً `no-cache`. schema: type: string example: no-cache content: application/json: schema: $ref: '#/components/schemas/Detail' examples: RateLimited: summary: حد الـ endpoint value: detail: >- Too many requests from this IP address. Please wait before trying again. Expected available in 60 seconds. BotProtection: summary: حد الحماية من البوت (POST وDELETE) value: detail: rate_limited Expected available in 2 seconds. TemporarilyUnavailable: description: >- خدمة يعتمد عليها الطلب غير متوفرة لفترة وجيزة. أعد المحاولة مع التراجع التدريجي. headers: Cache-Control: description: 'دائماً `no-store`: لا تقم بتخزين هذه الاستجابة مؤقتاً أبداً.' schema: type: string example: no-store Pragma: description: دائماً `no-cache`. schema: type: string example: no-cache content: application/json: schema: $ref: '#/components/schemas/OAuthError' examples: TemporarilyUnavailable: summary: إعادة المحاولة لاحقاً value: error: temporarily_unavailable securitySchemes: AccessToken: type: http scheme: bearer bearerFormat: JWT description: >- token الوصول الخاص بالشخص من `POST /token/`: عبارة عن ES256 JWT برأس `typ: at+jwt`، صالح لمدة 5 دقائق كحد أقصى. ليس مفتاح API الخاص بك في Didit. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.