الانتقال إلى المحتوى الرئيسي
تدعم Truthlocks طرق مصادقة متعددة لتأمين الوصول إلى واجهة برمجة التطبيقات (API). يغطي هذا الدليل مفاتيح API، ورموز JWT، وأفضل ممارسات الأمان.

طرق المصادقة

مفاتيح API

بيانات اعتماد طويلة الأمد للاتصال من خادم إلى خادم. موصى بها لـ خدمات الواجهة الخلفية.

رموز الحامل (JWT)

رموز قصيرة الأجل للمستخدمين المصادق عليهم. مثالية لتطبيقات الواجهة الأمامية وسياق المستخدم.

مفاتيح API

لدى Truthlocks نوعان من مفاتيح API اعتمادًا على كيفية استخدامك للمنصة:

تمرير مفتاحك

قم بتضمين مفتاح API الخاص بك باستخدام أحد هذين الرأسين:
يمكنك أيضًا استخدام رأس Authorization مع مخطط ApiKey:
تُصادق هذه التنسيقات نقاط نهاية ممكّنة بمفتاح API. تتطلب بعض العمليات رمز حامل مستخدم وفحوصات دور، ولا تحتاج نقاط نهاية الصحة العامة إلى أي منهما. X-API-Key أكثر شيوعًا في الأمثلة في جميع أنحاء هذا التوثيق.

مفاتيح API للمستأجر

مفاتيح المستأجر هي طريقة المصادقة الأساسية للمؤسسات التي تستخدم Truthlocks. وهي محددة النطاق لمستأجر وتدعم أذونات دقيقة.

هيكل المفتاح

النطاقات

يمكن تقييد مفاتيح API للمستأجرين على أذونات محددة:
مبدأ الحد الأدنى من الامتيازات: امنح فقط النطاقات التي يحتاجها تطبيقك. يحتاجها بالفعل. يجب ألا يحتوي المفتاح الذي يحتوي على attestations:mint فقط على users:write.

إنشاء مفتاح مستأجر

عبر وحدة التحكم

  1. انتقل إلى console.truthlocks.com/api-keys
  2. انقر على “إنشاء مفتاح API”
  3. أدخل اسمًا وصفيًا (على سبيل المثال، “الواجهة الخلفية للإنتاج”)
  4. حدد البيئة (الإنتاج أو بيئة الاختبار) والنطاقات المطلوبة
  5. انسخ المفتاح فورًا — لن يتم عرضه مرة أخرى

عبر واجهة برمجة التطبيقات

Request
Response
هام: يتم إرجاع حقل secret مرة واحدة فقط عند الإنشاء. قم بتخزينه. على الفور في مدير الأسرار.

مفاتيح API للمستهلك

تسمح مفاتيح المستهلك للمستخدمين الفرديين بالوصول إلى واجهات برمجة تطبيقات الحماية والتحقق برمجيًا — على سبيل المثال، لسك الشهادات من خط أنابيب CI أو دمج حماية المحتوى في أدواتك الخاصة.

التفاصيل الرئيسية

  • يدعم كل حساب ما يصل إلى 5 مفاتيح نشطة.
  • تنتهي صلاحية المفاتيح تلقائيًا بعد 90 يومًا.
  • لا يمكن إعادة تنشيط المفاتيح الملغاة أو منتهية الصلاحية — قم بإنشاء مفتاح جديد بدلاً من ذلك.

نطاقات ثابتة

يتم إصدار مفاتيح المستهلك بمجموعة ثابتة من النطاقات لا يمكن تخصيصها:

إنشاء مفتاح مستهلك

1

فتح الإعدادات

في الشريط الجانبي لبوابة التحقق، انتقل إلى الإعدادات > مفاتيح API.
2

إنشاء مفتاح

انقر فوق إنشاء مفتاح API، وأدخل اسمًا وصفيًا، ثم قم بالتأكيد. المفتاح الكامل يتم عرض السر مرة واحدة — انسخه وخزنه بأمان.
3

استخدم المفتاح

مرر المفتاح في رأس X-API-Key مع كل طلب:
للحصول على تفاصيل كاملة حول إدارة مفاتيح المستهلك، راجع consumer portal guide.

رموز Bearer (JWT)

تُستخدم رموز JWT عندما تحتاج إلى إجراء مكالمات API نيابة عن مستخدم مصادق عليه، مثل من تطبيق ويب أو جوال.

استخدام رموز الحامل

هيكل الرمز المميز

مدة صلاحية الرمز المميز

المصادقة متعددة العوامل للمصادق لحسابات Console

في Console، افتح Settings → Security → Authenticator MFA لربط Google Authenticator أو تطبيق مصادقة آخر يعتمد على الوقت.
  1. تأكيد كلمة مرور Truthlocks المحلية الحالية الخاصة بك.
  2. امسح رمز QR الخاص، أو أدخل مفتاح الإعداد في تطبيق المصادقة الخاص بك كحساب يعتمد على الوقت.
  3. أدخل الرمز المكون من ستة أرقام من التطبيق لتمكين المصادقة متعددة العوامل (MFA).
  4. احفظ رموز الاسترداد العشرة المعروضة بعد التأكيد. يتم عرضها مرة واحدة، ويعمل كل رمز مرة واحدة.
تتطلب عمليات تسجيل الدخول الجديدة العامل الثاني بعد كلمة المرور الخاصة بك أو مزود هوية عملك. تنتهي صلاحية خطوة التحقق بعد خمس دقائق. تؤدي الرموز غير الصحيحة المتكررة إلى قفل التحقق مؤقتًا للحساب. لا يمكن إعادة استخدام رمز تم قبوله بالفعل. لاستبدال رموز الاسترداد أو تعطيل المصادقة متعددة العوامل (MFA)، قم بتأكيد كلمة المرور الخاصة بك ورمز مصادقة جديد أو رمز استرداد غير مستخدم. يؤدي استبدال رموز الاسترداد إلى إبطال المجموعة السابقة. يمكن لمستخدمي تسجيل الدخول الموحد (SSO) الذين لم يقموا بتعيين كلمة مرور Truthlocks محلية مطلقًا استخدام تدفق إعادة تعيين كلمة المرور لبريدهم الإلكتروني المسجل قبل التسجيل. ينطبق تسجيل المصادقة متعددة العوامل (MFA) على حسابك الخاص. لا يسجل أعضاء آخرين أو يفرض متطلب MFA على مستوى مساحة العمل. لا يؤدي تمكين MFA إلى إلغاء الجلسات الحالية تلقائيًا. تظل مفاتيح API بيانات اعتماد نظام منفصلة.

أفضل ممارسات الأمان

✅ استخدام إدارة الأسرار

قم بتخزين مفاتيح API في Google Secret Manager أو HashiCorp Vault أو ما شابه ذلك. لا تقم أبدًا مفاتيح مشفرة في كود التطبيق.

✅ تدوير المفاتيح بانتظام

أنشئ مفاتيح جديدة وقم بإلغاء المفاتيح القديمة بشكل دوري. استخدم أسماء وصفية مع التواريخ (مثل “Backend-2026-Q1”).

✅ تقييد النطاقات

امنح الأذونات المطلوبة فقط. راجع ودقق نطاقات المفاتيح بانتظام.

❌ لا تعرض أبدًا في الواجهة الأمامية

يجب عدم تضمين مفاتيح API أبدًا في JavaScript من جانب العميل. استخدم رموز JWT لمصادقة الواجهة الأمامية.

❌ لا تقم أبدًا بالالتزام بـ Git

استخدم متغيرات البيئة أو إدارة الأسرار. أضف .env* إلى .gitignore.

الخطوات التالية

بوابة المستهلك

إدارة مفاتيح API للمستهلك، والحماية، والإعدادات.

البيئات

تكوين بيئة الاختبار مقابل الإنتاج وعناوين URL الأساسية.

التحكم في الوصول المستند إلى الدور (RBAC) والأذونات

فهم الأدوار والأذونات والتحكم في الوصول.

سجلات التدقيق

تتبع جميع أنشطة API والأحداث الأمنية.