الانتقال إلى المحتوى الرئيسي

نظرة عامة

Didit هي منصة التحقق من الهوية الأكثر ملاءمة للوكلاء الذكيين. يمكن لوكلاء البرمجة بالذكاء الاصطناعي (Cursor وClaude Code وGitHub Copilot وDevin وOpenHands وCodex) التسجيل، وضبط سير العمل، وبدء التحقق من الهويات، كل ذلك برمجياً ودون فتح متصفح أبداً. لماذا يفضّل الوكلاء Didit:
  • استدعاءان لواجهة API فقط من الصفر حتى الحصول على بيانات الاعتماد (التسجيل والتحقق من البريد الإلكتروني).
  • لا حاجة إلى متصفح: التشغيل بلا واجهة بالكامل، وهو مناسب تماماً لـ CI/CD ولسير عمل الوكلاء.
  • لا يوجد عامل تحقق ثانٍ لحساب API جديد: تُعاد الرموز فور التحقق من البريد الإلكتروني.
  • إنشاء تلقائي للمؤسسة والتطبيق مع api_key في استجابة التحقق.
  • واجهة إدارة كاملة: اضبط سير العمل والاستبيانات والقوائم والفوترة، كل ذلك عبر API.
  • خادم MCP متاح: يمكن للوكلاء اكتشاف أدوات Didit واستخدامها بشكل أصلي.
يُنشر العقد الكامل في openapi-auth.json، وقد دُققت نقاط النهاية أدناه بالمقارنة معه.

عنوان URL الأساسي

تقع جميع نقاط النهاية في هذا الدليل على مضيف المصادقة:
هذا المضيف مختلف عن واجهة التحقق البرمجية (https://verification.didit.me/v3). يُصدر مضيف المصادقة رموز الوصول JWT ويدير التطبيقات. أما مضيف التحقق فيُشغّل الجلسات وفحوص AML وسير العمل وغيرها، وتتم المصادقة على حركة واجهة التحقق البرمجية باستخدام api_key طويل الأمد الذي تحصل عليه من هذا التدفق.

البدء السريع

استخدم عنوان بريد إلكتروني حقيقي يمكن الوصول إليه. يُرسل نقطة النهاية رمز التحقق بشكل متزامن، لذلك تُرفض نطاقات الاختبار المحجوزة (@example.com و@example.org و@*.test و@*.example و@*.invalid) من خدمة البريد، ويعيد الاستدعاء حالة 500. استبدل العنصر النائب you@yourdomain.com أدناه بصندوق بريد يمكنك الوصول إليه.

الخطوة 1: التسجيل

الاستجابة (201 Created):
يُرسل رمز تحقق أبجدي رقمي من 6 خانات (مثل A3K9F2) إلى عنوان البريد الإلكتروني. تنتهي صلاحية الرمز بعد 10 دقائق من إرساله. إذا انتهت صلاحيته، فاستدعِ نقطة النهاية هذه مرة أخرى بالبريد الإلكتروني وكلمة المرور نفسيهما: بالنسبة إلى حساب لم يُتحقق منه بعد، ستعيد الاستجابة الرمز 200 مع الرسالة "A new verification code has been sent to your email." ورمزاً جديداً. كما تُعيد نقطة النهاية المخصصة POST /programmatic/resend-otp/ (الجسم: {"email", "password"}) إرسال الرمز، مع فترة انتظار 60 ثانية بين كل إرسال والآخر. يشترك المساران في حد المعدل الخاص بالتسجيل المذكور أدناه.

الخطوة 2: التحقق من الرمز والحصول على بيانات الاعتماد

الاستجابة (200 OK):
أصبح لديك الآن كل ما تحتاجه. احفظ application.api_key بأمان، وأرسله كترويسة x-api-key مع كل استدعاء لواجهة التحقق البرمجية.
رموز الوصول هي JWT موقّعة بخوارزمية RS256. القيمة الافتراضية لـ expires_in هي 86400 ثانية (24 ساعة). لا يلزم رمز الوصول إلا لنقاط نهاية الإدارة على apx.didit.me/auth/v2. أما حركة واجهة التحقق البرمجية على verification.didit.me/v3 فتُصادَق بـ api_key طويل الأمد، لا بـ JWT.

الخطوة 3: استخدام الواجهة البرمجية

عمليات تسجيل الدخول اللاحقة

من أي جهاز في المستقبل، استبدل بريدك الإلكتروني وكلمة المرور برمز JWT جديد:
تُعيد نقطة النهاية access_token وrefresh_token مباشرة، دون الحاجة إلى متصفح. بعد ذلك، استدعِ GET /organizations/me/ لاكتشاف org_id (وهو uuid الخاص بالمؤسسة)، ثم GET /organizations/me/{org_id}/applications/ لعرض تطبيقات المؤسسة (يمثل uuid في كل عنصر app_id)، وأخيراً GET /organizations/me/{org_id}/applications/{app_id}/ لاسترجاع api_key.
يمكن للحسابات التي أُنشئت من الكونسول بالبريد الإلكتروني وكلمة المرور أن تستخدم أيضاً POST /programmatic/login/ بعد التحقق من البريد الإلكتروني. أما حسابات الكونسول التي تعتمد على OAuth فقط، فتحتاج إلى تعيين كلمة مرور قبل استخدام نقطة نهاية تسجيل الدخول البرمجية هذه.

عندما يطلب تسجيل الدخول المزيد

تُعيد POST /programmatic/login/ الرموز فقط عندما لا يكون للحساب عامل تحقق ثانٍ. توجد ثلاث إجابات أخرى ممكنة، ويجب على الوكيل الذي يكتب سكربت تسجيل الدخول التعامل معها: لا يحتاج مفتاح API إلى تسجيل دخول، لذلك استخدمه في كل ما هو آلي. الحساب الذي لديه عامل تحقق ثانٍ لا يمكنه إتمام تسجيل الدخول عبر نقطة النهاية هذه.

متطلبات كلمة المرور

تُفرض على الخادم قاعدة واحدة في كل مرة، إذ يوقف الفشل الأول التحقق ويُعاد خطأ بصيغة مصفوفة مباشرة، مثل ["Password must contain at least one uppercase letter."]. (تستخدم أخطاء التحقق الأخرى في نقطة النهاية هذه الغلاف {"password": [...]} المفهرس بالحقول. وشكل المصفوفة المباشرة في قواعد قوة كلمة المرور عدم اتساق معروف في الخادم، فعامله معاملة {"password": [...]} في كود العميل.)

حدود المعدل والقفل

ثلاثة ضوابط مستقلة تحمي مضيف المصادقة. أيٌّ منها قد يُطلق استجابة 429، ورأس الاستجابة Retry-After يخبرك بالمدة التي يجب أن تنتظرها قبل إعادة المحاولة. يبدو نص استجابة 429 كما يلي:
حدود معدل واجهة برمجة التحقق (مثلاً 600 جلسة/دقيقة) مستقلة عن هذه الحدود، وموثقة في تحديد المعدل.

إدارة التطبيقات

بعد المصادقة، يمكنك استرجاع التطبيقات وإنشاؤها وتحديثها داخل مؤسستك. هذا الخيار مناسب تماماً للموزّعين الذين يريدون تطبيقاً واحداً لكل عميل. لكل تطبيق client_id وapi_key وبيانات وصفية وإعدادات خاصة به. ويفيد أيضاً حين تملك مؤسستك منتجات أو علامات تجارية أو مناطق أو بيئات أو حالات استخدام مختلفة تريد فصلها.
استرجاع التطبيقات وإنشاؤها وتحديثها يتطلب أن يكون المستخدم مالكاً أو مسؤولاً للمؤسسة المستهدفة، وإلا فستكون الاستجابة 403.

ماذا يمكن للوكلاء فعله بعد التسجيل

باستخدام api_key، يتمتع الوكلاء بوصول كامل إلى واجهة برمجة التحقق. المسارات المدققة على https://verification.didit.me/v3 هي: راجع مرجع واجهة برمجة الإدارة للاطلاع على الواجهة الكاملة.

تكامل خادم MCP

للحصول على أفضل تجربة للوكلاء، استخدم خادم Didit MCP المستضاف على https://mcp.didit.me/mcp. لا يحتاج إلى مفتاح API: عند الاتصال الأول، يفتح عميلك المتصفح، وتضغط على تسجيل الدخول باستخدام Didit (OAuth 2.1 مع PKCE)، ويعمل الخادم نيابةً عنك بصلاحيات دورك في وحدة التحكم. العملاء الذين يدعمون MCP البعيد بشكل أصلي (Cursor وVS Code) يأخذون هذا الإدخال، أما Claude على الويب وDesktop فيضيفانه كموصل مخصص:
Claude Code: claude mcp add --transport http didit https://mcp.didit.me/mcp. العملاء الذين يدعمون stdio فقط (Windsurf وZed) يمرون عبر الجسر mcp-remote، الذي يُنفّذ تدفق OAuth نيابةً عنك. مفتاح API الذي تحصل عليه من تدفق التسجيل أعلاه مخصص لاستدعاء REST API من الخلفية الخاصة بك، ولا يستخدمه MCP أبداً. للتفاصيل، راجع نظرة عامة على MCP والتثبيت الخاص بكل عميل.

مرجع غلاف الأخطاء

تشترك جميع endpoint الخاصة بـ apx.didit.me/auth/v2 في أشكال الاستجابة الثلاثة نفسها (راجع openapi-auth.json):
  • التحقق على مستوى الحقول: {"field": ["message", ...]} مع HTTP 400.
  • التحقق على مستوى النموذج (خصوصاً قوة كلمة المرور وأخطاء رمز التحقق): مصفوفة مجردة ["Invalid or expired verification code."] مع HTTP 400.
  • قواعد المصادقة أو قواعد العمل: {"detail": "..."} مع 400 أو 401 أو 403 أو 404 أو 429. تحمل استجابات 429 الرأس Retry-After الذي يخبرك بمدة الانتظار قبل إعادة المحاولة (ويحتوي جسم الاستجابة على detail فقط).
يعيد مضيف التحقق الأخطاء بصيغة {"detail": "..."}، وتتضمن استجابات 429 الرأسين X-RateLimit-* وRetry-After. راجع تحديد المعدل.
آخر تعديل في ٧ نوفمبر ٢٠٢٦