رمز API
يتيح رمز API (token) لبرنامج خارجي استدعاء نقاط وصول API الخاصة بـ Omniscol باسم المدرسة، للقراءة، وللكتابة أيضاً إذا حُددت نقاط وصول API للكتابة.
هذه أداة قوية، ولذلك يجب التعامل معها بحذر.
الإنشاء
يُنشأ الرمز في مشاركة (استيراد / تصدير > مشاركة). عليكم تحديد:
- مفتاح (يُنشأ في Omniscol، مع تسمية وتاريخ انتهاء اختياري؛ ويمكن تعديل تاريخ انتهائه لاحقاً)،
- النطاق: قائمة نقاط وصول API التي يستطيع هذا الرمز استدعاءها (لا تمنحوا إلا ما هو ضروري تماماً)،
- وعند الحاجة تاريخ انتهاء الرمز. يُدرج هذا التاريخ في JWT المُنشأ ولا يمكن تعديله بعد ذلك.
يؤدي حذف المفتاح، أو بلوغ تاريخ انتهائه، إلى إلغاء الرموز المشتقة منه فوراً. لتغيير تاريخ انتهاء رمز بعينه، أنشئوا JWT جديداً.
الاستخدام
يُرسل الرمز في ترويسة HTTP Authorization: Bearer <token>،
أو (وهو غير مستحسن في الإنتاج) في الرابط عبر ?auth=<token>.
أفضل الممارسات
- مفتاح لكل تكامل: يسهّل الإلغاء المستقل.
- الحد الأدنى من النطاق: حددوا فقط نقاط API الضرورية، لا الكل افتراضياً.
- انتهاء الصلاحية في المستوى المناسب: استخدموا تاريخ انتهاء المفتاح لإدارة تكامل على المدى الطويل، واستخدموا تاريخ انتهاء الرمز لوصول مؤقت غير قابل للتعديل.
- تجديد دوري: أعيدوا إنشاء المفتاح كل 6 إلى 12 شهراً.
- لا تضعوه في Git: يجب ألا ينتهي الرمز في مستودع عام ضمن نظام التحكم في الإصدارات. استخدموا متغيرات البيئة في خادمكم.
الفرق بينه وبين OIDC / SSO
لربط مستخدمين حقيقيين بهويتهم المؤسسية، راجعوا OIDC / SSO. أما رمز API فهو مخصص للتكاملات التقنية بين الخوادم، وليس لتسجيل دخول المستخدمين اليومي.