> ## 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. # الحصول على مفاتيح التوقيع (JWKS) | Didit > يعيد GET /.well-known/jwks.json المفاتيح العامة ES256 لتطبيقك في Didit. خزّنها مؤقتاً حسب kid؛ تُدوَّر كل 30 يوماً مع تداخل يوم واحد. > [!WARNING] > > المصادقة ميزة جديدة. تُقدَّم هذه endpoints من جهة الإصدار الخاصة بتطبيقك، مثل `https://.auth.didit.me`، ولا تقبل مفتاح API الخاص بـ Didit أبدًا. تتغيّر المفاتيح كل 30 يومًا، مع فترة تداخل مدتها يوم على كل جانب، لذا يستمر JWKS المخزَّن مؤقتًا لمدة 5 دقائق في التحقق عبر عملية التدوير. أعِد جلبه عندما يشير token إلى `kid` لا تملكه، بحد أقصى مرة واحدة في الدقيقة. راجع [التخزين المؤقت والتدوير](https://docs.didit.me/ar/authentication/tokens-and-jwks.md#التخزين-المؤقت-والتدوير). ## OpenAPI ````yaml ar/openapi-authentication.json GET /.well-known/jwks.json 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: /.well-known/jwks.json: get: tags: - Issuer summary: الحصول على مفاتيح التوقيع description: >- مفاتيح ES256 العامة للتطبيق. يُحدد كل token مفتاحه في الرأس `kid`. يتم تدوير المفاتيح كل 30 يوماً. يتم نشر المفتاح التالي قبل يوم واحد من بدء التوقيع به، ويظل المفتاح السابق منشوراً لمدة يوم بعد توقفه، وبالتالي يستمر JWKS المخزن مؤقتاً لمدة تصل إلى 5 دقائق في التحقق عبر التدوير. قم بتخزين المفاتيح مؤقتاً بحسب `kid` واجلب JWKS مرة أخرى عندما يُحدد token معرّف `kid` ليس لديك، بمعدل لا يتجاوز مرة واحدة في الدقيقة كحد أقصى. عندما تُبطل Didit مفتاحاً مخترقاً، يخرج المفتاح من هذا المستند على الفور ويرفض `GET /session/` كل token تم توقيعه به. يبدأ المفتاح البديل بالتوقيع فوراً، دون النشر المسبق بيوم واحد، وبالتالي فإن JWKS المخزن مؤقتاً قبل ما يصل إلى 5 دقائق سيظل يقبل المفتاح الملغى ولا يتعرف على المفتاح البديل بعد. operationId: authentication_get_jwks responses: '200': description: المفاتيح المنشورة. headers: Cache-Control: description: >- `public, max-age=300`: يمكنك أنت وذاكرات التخزين المؤقت المشتركة الاحتفاظ باستجابة ناجحة لمدة 5 دقائق، وهي مدة صلاحية token الوصول الواحد. schema: type: string example: public, max-age=300 content: application/json: schema: $ref: '#/components/schemas/JSONWebKeySet' examples: Keys: summary: مفتاح توقيع واحد value: keys: - kty: EC crv: P-256 x: ZDN2unLMultuZwNY_ZKMvsKLRrlC_usPFZyK77cnDO8 'y': CfLKoaJNvhFpDWqG56H8dD_j0f1c93RdR63bhIdTh3I kid: k_8sJ2dQvX0nLr5TfYb3HkPw use: sig alg: ES256 '403': $ref: '#/components/responses/OriginNotAllowed' '404': $ref: '#/components/responses/ApplicationNotFound' '429': $ref: '#/components/responses/RateLimited' '503': $ref: '#/components/responses/TemporarilyUnavailable' security: - {} components: schemas: JSONWebKeySet: type: object description: >- مفاتيح توقيع التطبيق العامة المنشورة. عادةً مفتاح واحد؛ أو مفتاحان في فترة التدوير، عندما يتم نشر المفتاح التالي قبل يوم من توقيعه ويظل المفتاح السابق يوماً بعد توقفه. required: - keys properties: keys: type: array items: $ref: '#/components/schemas/JSONWebKey' JSONWebKey: type: object description: مفتاح عام P-256 بصيغة JWK ‏(RFC 7517). required: - kty - crv - x - 'y' - kid - use - alg properties: kty: type: string enum: - EC crv: type: string enum: - P-256 x: type: string description: الإحداثي x للنقطة العامة، بترميز base64url. example: ZDN2unLMultuZwNY_ZKMvsKLRrlC_usPFZyK77cnDO8 'y': type: string description: الإحداثي y للنقطة العامة، بترميز base64url. example: CfLKoaJNvhFpDWqG56H8dD_j0f1c93RdR63bhIdTh3I kid: type: string description: >- معرّف المفتاح، وهو `kid` الموجود في رأس كل token يوقعه هذا المفتاح. تبدأ معرّفات المفاتيح الجديدة بـ `k_`. example: k_8sJ2dQvX0nLr5TfYb3HkPw use: type: string enum: - sig alg: type: string enum: - ES256 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: 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 ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.