> ## 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. # إنشاء token المراقبة | واجهة برمجة تطبيقات Didit للمصادقة > يستبدل POST /monitoring-token/ رمز الوصول ببيانات اعتماد جهاز لمدة 15 دقيقة، مرتبطة بـ vendor_data للشخص وأصل المتصفح في Didit. > [!WARNING] > > المصادقة ميزة جديدة، وتبقى نقطة النهاية هذه معطّلة إلى أن تفعّلها Didit: حتى ذلك الحين تُرجع `503 monitoring_unavailable`. تستدعي حزمتا SDK للمتصفح والتطبيقات الأصلية هذا الـ endpoint من جهاز الشخص، ولا يحتاج خادمك إلى ذلك. يُسجَّل كل حدث يُرسل مع بيانات الاعتماد ضمن `vendor_data` الخاصة بالشخص، مهما ادّعى الجهاز غير ذلك. ## OpenAPI ````yaml ar/openapi-authentication.json POST /monitoring-token/ 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: /monitoring-token/: post: tags: - Monitoring summary: أنشئ token للمراقبة description: >- يستبدل token وصول الشخص ببيانات اعتماد جهاز قصيرة الأجل، حتى يتمكن متصفح الشخص أو تطبيقه من إرسال أحداث النشاط إلى مراقبة المعاملات دون الرجوع إلى واجهتك الخلفية. ترتبط بيانات الاعتماد بـ `vendor_data` الخاصة بالشخص وبـ `Origin` الخاص بالطلب. تستدعي حزم SDK للمتصفح والأنظمة الأصلية هذا الـ endpoint؛ أما حزم SDK للخادم فلا تستدعيه. تكون الميزة معطّلة حتى تُفعّلها Didit، وتُرجع `503 monitoring_unavailable` حتى ذلك الحين. operationId: authentication_create_monitoring_token requestBody: required: false content: application/json: schema: $ref: '#/components/schemas/MonitoringTokenRequest' example: {} responses: '201': 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/MonitoringToken' examples: MonitoringToken: summary: بيانات اعتماد لمتصفح الشخص value: monitoring_token: mt_2f8c1d9e7b6a5f4e3d2c1b0a expires_at: '2026-10-17T10:56:14Z' allowed_event_categories: - session - gameplay - bonus - affiliate - payment - dispute - responsible_gambling - custom max_uses: 1000 bind_to_origin: https://app.example.com vendor_data: user-42 '400': 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/FieldErrors' examples: UnknownField: summary: حقل في نص الطلب value: vendor_data: unknown_field '401': $ref: '#/components/responses/InvalidToken' '403': $ref: '#/components/responses/OriginNotAllowed' '404': $ref: '#/components/responses/ApplicationNotFound' '409': 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: MonitoringDisabled: summary: استيعاب الأحداث متوقف value: error: monitoring_disabled '429': $ref: '#/components/responses/RateLimited' '503': description: >- token للمراقبة غير مُمكّن، أو تعذر على المراقبة إصداره (`monitoring_unavailable`)، أو أن هناك خدمة يعتمد عليها الطلب غير متوفرة لفترة وجيزة (`temporarily_unavailable`). أعد المحاولة لاحقاً. 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: MonitoringUnavailable: summary: غير متاح value: error: monitoring_unavailable TemporarilyUnavailable: summary: إعادة المحاولة لاحقاً value: error: temporarily_unavailable security: - AccessToken: [] components: schemas: MonitoringTokenRequest: type: object description: 'فارغ: يحدد token الوصول اسم الشخص.' additionalProperties: false properties: {} MonitoringToken: type: object description: >- بيانات اعتماد جهاز قصيرة الأجل لإرسال أحداث نشاط الشخص إلى مراقبة المعاملات من جهازه. وهي غير مرتبطة بالجلسة: تظل قابلة للاستخدام حتى `expires_at`، حتى بعد تسجيل الخروج. required: - monitoring_token - expires_at - allowed_event_categories - max_uses - bind_to_origin - vendor_data properties: monitoring_token: type: string description: بيانات اعتماد الجهاز. تعامل معها كسرّ. example: mt_2f8c1d9e7b6a5f4e3d2c1b0a expires_at: type: string format: date-time description: في غضون 15 دقيقة على الأكثر بعد إصداره. example: '2026-10-17T10:56:14Z' allowed_event_categories: type: array items: type: string description: >- فئات الأحداث التي قد يرسلها. تأتي أحداث المصادقة والأمان دائماً من Didit، ولا تأتي أبداً من الجهاز. example: - session - gameplay - bonus - affiliate - payment - dispute - responsible_gambling - custom max_uses: type: integer example: 1000 bind_to_origin: type: string nullable: true description: >- أصل المتصفح الذي تعمل بيانات الاعتماد منه: قيمة `Origin` الخاصة بالطلب، أو `null` في حال عدم وجودها. example: https://app.example.com vendor_data: type: string description: الشخص الذي يُسجَّل كل حدث لأجله، أياً كان ما يرسله الجهاز. example: user-42 FieldErrors: title: Field errors type: object description: >- أخطاء التحقق حسب الحقل. تكون القيمة عبارة عن قائمة من الرسائل، أو رمز واحد (`unknown_field`، `invalid_redirect_uri`). يحتوي `non_field_errors` على القواعد المطبقة عبر حقول متعددة. additionalProperties: oneOf: - type: string - type: array items: type: string OAuthError: title: OAuth error type: object description: خطأ OAuth (القسم 5.2 من RFC 6749) أو خطأ في الخدمة. required: - error properties: error: type: string example: invalid_grant Detail: type: object required: - detail properties: detail: type: string example: invalid_token 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. 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.