> ## 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 /session/ من رمز الوصول مقابل الجلسة الحية في Didit، فيفشل فوراً عند الإبطال أو انتهاء مهلة الخمول أو الحظر أو التحديث. > [!WARNING] > > المصادقة ميزة جديدة. تُقدَّم هذه endpoints من خلال المُصدِر الخاص بتطبيقك، مثل `https://.auth.didit.me`، ولا تقبل أبدًا مفتاح API الخاص بك في Didit. هذا فحص الإلغاء الفوري. يسمح بـ 30 طلبًا في الدقيقة و300 طلب في الساعة لكل عنوان IP، لذا تحقّق من token دون اتصال في كل طلب، واستدعه قبل الإجراءات الحساسة. راجع [تحقق من الجلسة](https://docs.didit.me/ar/authentication/tokens-and-jwks.md#التحقق-من-الجلسة). ## OpenAPI ````yaml ar/openapi-authentication.json GET /session/ 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: /session/: get: tags: - Sessions summary: الحصول على الجلسة description: >- يتحقق من token الوصول مقابل الجلسة المباشرة ويرجعه. وهو أكثر صرامة من التحقق من JWT بنفسك: إذ يفشل على الفور عند إلغاء الجلسة، أو خمولها، أو تجاوز مدة صلاحيتها، أو عند حظر الشخص أو عدم التحقق من بريده الإلكتروني بعد الآن، أو عندما لا تعد الجلسة متوافقة مع سياسة المصادقة متعددة العوامل (MFA) الخاصة بك (على سبيل المثال بعد إضافة الشخص لتطبيق مصادقة أو ترقيته إلى مسؤول المؤسسة)، أو عند استبدال token عبر التحديث. استخدمه قبل أي إجراء حساس، مثل صرف الأموال. يُحتسب التحقق الناجح كنشاط، وبالتالي يعيد تعيين مهلة خمول الجلسة. operationId: authentication_get_session 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/Session' examples: Session: summary: جلسة كلمة مرور value: sub: 1c9d8b88-1bff-43d1-ad7a-88b2bc0024e9 sid: c9abf6cc-2d64-4bf2-b31e-a4d09a070ab1 application_id: 7b0a6c2e-3f41-4c9a-8d55-1e2f3a4b5c6d vendor_data: user-42 amr: - password mfa_verified: false email: person@example.com email_verified: true phone: null verified_identity: null verified: null expires_at: '2026-11-16T10:41:14.347557Z' post_logout_redirect_uri: '' organizations: [] VerifiedMember: summary: عضو مؤسسة تم التحقق منه value: sub: 1c9d8b88-1bff-43d1-ad7a-88b2bc0024e9 sid: c9abf6cc-2d64-4bf2-b31e-a4d09a070ab1 application_id: 7b0a6c2e-3f41-4c9a-8d55-1e2f3a4b5c6d vendor_data: user-42 amr: - passkey mfa_verified: true email: person@example.com email_verified: true phone: '+34600000000' verified_identity: null verified: level: full_id over_18: true given_name: Alex country: ES expires_at: '2026-11-16T10:41:14.347557Z' post_logout_redirect_uri: https://app.example.com/ organizations: - organization_id: 3e9a1f0b-5c2d-4e7f-8a6b-9c0d1e2f3a4b organization__name: Northwind role: admin custom_role: null '401': $ref: '#/components/responses/InvalidToken' '403': $ref: '#/components/responses/OriginNotAllowed' '404': $ref: '#/components/responses/ApplicationNotFound' '429': $ref: '#/components/responses/RateLimited' '503': $ref: '#/components/responses/TemporarilyUnavailable' security: - AccessToken: [] components: schemas: Session: type: object description: الجلسة المباشرة المرتبطة بـ token الوصول. required: - sub - sid - application_id - vendor_data - amr - mfa_verified - email - email_verified - phone - verified_identity - verified - expires_at - post_logout_redirect_uri - organizations properties: sub: type: string format: uuid description: معرّف الهوية. example: 1c9d8b88-1bff-43d1-ad7a-88b2bc0024e9 sid: type: string format: uuid description: معرّف الجلسة. example: c9abf6cc-2d64-4bf2-b31e-a4d09a070ab1 application_id: type: string format: uuid example: 7b0a6c2e-3f41-4c9a-8d55-1e2f3a4b5c6d vendor_data: type: string description: مرجع الشخص عبر منتجات Didit، كما هو موضح في الـ token. example: user-42 amr: $ref: '#/components/schemas/AuthenticationMethods' mfa_verified: type: boolean description: >- ما إذا كانت الجلسة قد اجتازت عاملاً ثانياً. تكون دائماً `true` لتسجيل الدخول باستخدام مفتاح المرور. example: false email: type: string format: email nullable: true example: person@example.com email_verified: type: boolean example: true phone: type: string nullable: true description: رقم هاتف بتنسيق E.164، أو `null`. example: null verified_identity: $ref: '#/components/schemas/WalletVerification' verified: type: object nullable: true description: >- مستوى التحقق والمطالبات المحددة، وهو نفس الكائن الذي تحمله الرموز تحت `verified`، أو `null` عند عدم وجود أي منها. اقرأ هذا، وليس `email_verified`، لمعرفة ما إذا كان الشخص قد أجرى التحقق من هويته. properties: level: type: string enum: - liveness - liveness_face_match - full_id description: >- أعلى مستوى تم اجتيازه. من الأضعف إلى الأقوى: `liveness`، و`liveness_face_match`، و`full_id`. example: full_id over_18: type: boolean example: true over_21: type: boolean example: true given_name: type: string example: Alex family_name: type: string example: Doe birthdate: type: string description: تاريخ الميلاد من المستند، `YYYY-MM-DD`. example: '1990-04-12' nationality: type: string description: رمز الدولة وفقاً لـ ISO 3166-1 alpha-2. example: ES country: type: string description: رمز ISO 3166-1 alpha-2 لدولة المستند. example: ES document_verified: type: boolean example: true liveness: type: boolean example: true expires_at: type: string format: date-time description: متى تنتهي الجلسة كحد أقصى. يمكن لمهلة الخمول إنهاؤها قبل ذلك. example: '2026-11-16T10:41:14.347557Z' post_logout_redirect_uri: type: string description: >- المكان الذي يرسل تطبيقك الشخص إليه بعد تسجيل الخروج. سلسلة نصية فارغة عندما لا تكون معينة. example: https://app.example.com/ organizations: type: array description: >- كل مؤسسة عميل ينتمي إليها الشخص، عند تفعيل المؤسسات. وتكون فارغة بخلاف ذلك. items: $ref: '#/components/schemas/SessionOrganization' AuthenticationMethods: type: array description: >- طريقة تسجيل الدخول للجلسة، كقيمة واحدة: على سبيل المثال `password`، أو `code` (رمز البريد الإلكتروني)، أو `magic` (الرابط السحري)، أو `passkey`، أو `phone`، أو `sso`، أو `wallet` (محفظة Didit ID Wallet)، أو اسم طريقة تسجيل دخول عبر وسائل التواصل الاجتماعي. يكون فارغاً لـ token الخاص بالوكيل. items: type: string example: - password WalletVerification: type: object description: >- ما تمت مشاركته بواسطة Didit ID Wallet عند تسجيل الدخول. يكون `null` عندما يسجل الشخص دخوله بطريقة أخرى. nullable: true required: - issuer - subject properties: issuer: type: string description: الجهة المصدرة للمحفظة. example: https://apx.didit.me/auth/idv subject: type: string description: معرّف الشخص لدى المحفظة. example: 8b7f5c1e-2d3a-4b5c-9e8f-7a6b5c4d3e2f shared_session: type: object description: >- عملية تحقق اختار الشخص مشاركتها، وتقوم باستردادها باستخدام مفتاح API الخاص بك. properties: share_token: type: string session_id: type: string from_application_id: type: string claims: type: object description: >- الحقائق التي تم التحقق منها ووافق الشخص على مشاركتها، وتقتصر على ما طلبه تطبيقك. additionalProperties: oneOf: - type: boolean - type: string example: over_18: true given_name: Alex SessionOrganization: type: object required: - organization_id - organization__name - role - custom_role properties: organization_id: type: string format: uuid example: 3e9a1f0b-5c2d-4e7f-8a6b-9c0d1e2f3a4b organization__name: type: string description: اسم المؤسسة. example: Northwind role: type: string enum: - admin - member - billing example: admin custom_role: type: object nullable: true description: الدور المخصص الذي أُسند إلى العضو، أو `null`. required: - key - permissions properties: key: type: string example: approver permissions: type: array items: type: string example: - payouts.approve 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 ApplicationNotFound: description: >- العنوان يتبع تطبيقاً، ولكن المصادقة غير مفعّلة له؛ وعلى العنوان `apx.didit.me`، يكون معرّف التطبيق غير معروف. يتم رفض العنوان الذي لا يتبع أي تطبيق قبل أن يصل إلى endpoint، وتلك الاستجابة لا تكون بتنسيق JSON. 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: ApplicationNotFound: summary: تطبيق غير معروف value: detail: No Configuration matches the given query. 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.