إدارة مفاتيح API الخاصة بك
اعثر على مفتاح API الخاص بك ضمن API & Webhooks في الكونسول، واحتفظ به على الخادم فقط، واستخدم تطبيق sandbox منفصلًا للاختبار، وأصلح خطأي 401 و403.
API & Webhooks، بحسب التطبيق الذي اخترته. مفتاح واحد لكل تطبيق، والمفتاح هو البيئة نفسها - لا يوجد مفتاح اختبار منفصل على تطبيق مباشر. إنه سر يُستخدم من جهة الخادم فقط: لا يوضع أبدًا في شيفرة الواجهة الأمامية أو داخل حزمة تطبيق.
يوجد مفتاح API الخاص بك ضمن API & Webhooks في الشريط الجانبي للكونسول، بحسب التطبيق الذي تعمل عليه. تعامل معه كما تتعامل مع كلمة مرور - فهو يمنح وصولًا كاملًا إلى API نيابةً عن هذا التطبيق.
#العثور على مفتاحك
- سجّل الدخول إلى Business Console
اذهب إلى business.didit.me وسجّل الدخول.
- اختر تطبيقك
اختر التطبيق الذي تريده من القائمة المنسدلة أعلى الكونسول. لكل تطبيق مفتاحه الخاص.
- افتح API & Webhooks
يوجد مفتاح API الخاص بك هنا، إلى جانب وجهات webhook الخاصة بك وأسرار توقيعها.
- يُصدر Create API key مفتاحًا جديدًا؛ المفاتيح مخصصة لكل تطبيق على حدة.
- يُعرض السر هنا مرة واحدة فقط - انسخه إلى مخزن الأسرار الخاص بك.
- يستبدل Rotate secret السر دون تغيير اسم المفتاح.
- يساعدك Last used على تمييز مفتاح نشط من مفتاح منسي قبل إلغائه.
#مفتاح API وسر التوقيع أمران مختلفان
يستحق الأمر التوضيح الصريح، لأن الخلط بينهما ينتج أخطاءً مربكة:
| الغرض منه | أين | |
|---|---|---|
| مفتاح API | مصادقة طلباتك إلى Didit، ضمن ترويسة x-api-key | لكل تطبيق |
| سر توقيع webhook | التحقق من أن طلب webhook الوارد جاء فعلًا من Didit | لكل وجهة |
إرسال سر التوقيع كمفتاح API ينتج خطأ 401. التحقق من webhook باستخدام مفتاح API ينتج عدم تطابق في التوقيع. كلا الخطأين شائع.
مفتاح API الخاص بك سر. لا تضعه أبدًا في شيفرة الواجهة الأمامية، أو في مستودع عام، أو داخل حزمة تطبيق جوال - احتفظ به على الخادم فقط. المفتاح الموجود داخل حزمة تطبيق تم إصدارها هو مفتاح بات في يد مهاجم. راجع مصادقة API.
#الحصول على مفتاح للاختبار
لا تُجرِ اختباراتك على بيئة الإنتاج. أنشئ تطبيقًا منفصلًا في وضع sandbox - فجلسات sandbox تحاكي كل فحص خارجي، ولا تُفوتر أبدًا، ولا تلمس بيانات مستخدمين حقيقية. استخدم مفتاحه أثناء البناء، واحتفظ بتطبيق مباشر منفصل للتحققات الحقيقية.
لا يوجد "مفتاح اختبار" على تطبيق مباشر. المفتاح هو البيئة نفسها، لذا يستحق الأمر تسمية مفاتيحك بوضوح تام أينما احتفظت بأسرارك. راجع الاختبار في sandbox.
#تدوير مفتاحك
إذا كان من المحتمل أن مفتاحًا قد تعرّض للانكشاف، أعد توليده من صفحة API & Webhooks نفسها. تؤدي إعادة التوليد إلى إبطال المفتاح القديم فورًا، لذا حدّثه في كل مكان يُستخدم فيه أولًا - وإلا بدأت حركة الإنتاج لديك بالفشل في اللحظة التي تضغط فيها على الزر.
تدوير المفتاح وفق جدول زمني ممارسة جيدة. خطط له كعملية نشر، لا كمجرد ضغطة زر.
#إصلاح خطأي 401 و403
| الخطأ | السبب | الإصلاح |
|---|---|---|
401 | المفتاح مفقود أو غير صحيح الصيغة أو أُعيد توليده | انسخ المفتاح الحالي من API & Webhooks لهذا التطبيق. تحقق من عدم وجود مسافات أو علامات اقتباس زائدة، ومن أنك لم تلصق سر توقيع بالخطأ |
403 | المفتاح صحيح لكن هذا الطلب غير مسموح به | عادةً ما يكون السبب التطبيق الخاطئ، أو حقلًا مخصصًا لـ sandbox على مفتاح مباشر (أو العكس)، أو صلاحية ينقصها مفتاحك، أو ميزة غير مفعّلة في حسابك |
خطأ 403 على سير عمل محدد يعني في الغالب أن المفتاح ينتمي إلى تطبيق مختلف عن التطبيق الذي يملك سير العمل هذا. بدّل التطبيق في الكونسول وانسخ مفتاحه بدلًا من ذلك. التفاصيل الكاملة: أخطاء API ومعناها.
#تقييد ما يمكن أن يفعله المفتاح
إذا كانت حاجتك هي تحديد فئات البيانات التي يمكن لمفتاح ما الوصول إليها - على سبيل المثال لمنع خدمة ما من جلب صور المستندات - فهذه مسألة صلاحيات لا إعداد خاص بالمفتاح، وما هو متاح يعتمد على حسابك. اسأل الدعم بدلًا من افتراض أن المفتاح غير مقيَّد أو افتراض أنه مقيَّد؛ فكلا الافتراضين محفوف بالمخاطر في اتجاهين متعاكسين.
#من في فريقك يمكنه رؤية المفاتيح
رؤية المفاتيح تتبع الدور. دور Developer يشمل مفاتيح API؛ أما Reader فلا. إذا لم يتمكن أحد أعضاء فريقك من إيجاد الصفحة، تحقق من دوره قبل الإبلاغ عن ذلك كخلل. راجع دعوة أعضاء الفريق وتحديد الأدوار.
#كل طلب يُسجَّل
تظهر طلبات مفتاح API في Audit Logs، منسوبة إلى التطبيق لا إلى شخص، وهذا هو بالضبط سبب أن المفتاح المشترك بين عدة خدمات يجعل التحقيق في أي حادثة أصعب. مفتاح واحد لكل مستهلك أسهل في تتبعه. راجع استخدام سجلات التدقيق.