المصادقة
كل عملية، عدا فهرس السوق، تحتاج إلى بيانات اعتماد في الترويسة Authorization. وهي ثلاثة أنواع.
| مفتاح واجهة | رمز وصول شخصي | رمز وصول OAuth | |
|---|---|---|---|
| الترويسة | Bearer zk_live_… / Bearer zk_test_… | Bearer zpat_… | Bearer <JWT> |
| يعمل باسم | مؤسستك | الشخص الذي أنشأه | الشخص الذي سجّل الدخول إلى تطبيقك |
| يُنشأ في | استوديو المطوّرين (حي وتجريبي)؛ في وحدة التحكم الفريق ← مفتاح API جديد (حي) | POST /v1/api-tokens | تطبيقك، عبر auth.zaitrack.app |
| مدة الصلاحية | من يوم إلى 365 يومًا (الافتراضي 365) | من يوم إلى 365 يومًا | قصيرة؛ يُجدَّد برمز تحديث |
| استخدمه لـ | التكامل بين الخوادم | البرامج النصية التي تشغّلها باسمك | التطبيقات التي يسجّل الناس الدخول إليها |
أيًّا كان النوع، لا تحمل بيانات الاعتماد نطاقًا أوسع من نطاق منشئها.
مفاتيح الواجهة
مفتاح الواجهة ملك المؤسسة لا الشخص. يبدأ بـ zk_live_ (أو zk_test_) ثم 32 محرفًا بترميز base32 ثم _
ورمز تحقق من 16 محرفًا؛ وترفض البوابة المفتاح المشوّه دون بحث.
- النطاقات تُختار عند إنشاء المفتاح، ولا تتجاوز نطاقاتك.
- قائمة عناوين IP المسموح بها وتاريخ الانتهاء اختياريان؛ الطلب من عنوان آخر يتلقى
403، والمفتاح المنتهي401. - التدوير بـ
POST /v1/api-keys/{id}:rotate: يظهر السرّ الجديد مرة واحدة ويحتفظ بنطاقات المفتاح القديم. يبقى المفتاح القديم صالحًا 30 يومًا، أو حتى انتهائه إن كان أقرب، فتنتقل دون انقطاع. - الإبطال بـ
POST /v1/api-keys/{id}:revoke. يتوقف المفتاح المُبطل خلال 30 ثانية (ذاكرة البوابة المؤقتة).
تُنشأ المفاتيح في استوديو المطوّرين، حيّة أو تجريبية (المفتاح التجريبي على إحدى بيئاتك التجريبية)، أو مفاتيح حيّة في وحدة التحكم من الفريق ← مفتاح API جديد. لا توجد في الواجهة عملية لإنشائها.
رموز الوصول الشخصية
رمز الوصول الشخصي (zpat_…) يعمل باسمك، بنطاقاتك على الأكثر، وكل استخدام له يُدقَّق. أنشئه بـ
POST /v1/api-tokens وأنت مسجّل الدخول عبر OAuth: ترفض الخدمة هناك مفاتيح الواجهة وغيرها من بيانات الاعتماد
غير التفاعلية.
curl -X POST "https://api.zaitrack.app/v1/api-tokens" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"label": "Fuel import script", "scopes": ["fuel:read", "fuel:write"], "ttlDays": 30}'
يظهر الرمز في الرد مرة واحدة. اعرض رموزك بـ GET /v1/api-tokens، وأبطل أحدها بـ
POST /v1/api-tokens/{id}:revoke.
تطبيقات OAuth
سجّل تطبيقًا في استوديو المطوّرين (تطبيقات OAuth ← تسجيل تطبيق) للبرامج التي يسجّل الناس الدخول إليها.
- المُصدِر:
https://auth.zaitrack.app/(Ory Hydra). اقرأ نقاط النهاية منhttps://auth.zaitrack.app/.well-known/openid-configuration. - نوع المنح: رمز التفويض (authorization code) مع رموز التحديث. لا يوجد منح client credentials للتطبيقات: الخادم الذي لا يقف خلفه شخص يستخدم مفتاح واجهة.
- التطبيقات العامة (صفحة واحدة، جوال، سطح مكتب) بلا سرّ وتستخدم PKCE (أرسل
code_challenge_method=S256). - التطبيقات السرية (تطبيق ويب على الخادم) تحصل على سرّ عميل يظهر مرة واحدة ويُرسل بـ HTTP Basic
(
client_secret_basic). التدوير يُظهر سرًّا جديدًا. - عناوين إعادة التوجيه بـ
https، أوhttp://localhostللتطوير. - النطاقات لا تتجاوز ما تمنحه أدوار مؤسستك وما تملكه أنت عند تسجيل التطبيق.
- من يسجّل الدخول: أعضاء مؤسستك فقط. لا توجد شاشة موافقة بعد.
- الحذف يزيل التطبيق ويُبطل رموز التحديث فورًا؛ ويبقى رمز الوصول الصادر صالحًا حتى انتهائه (15 دقيقة).
النطاقات
النطاق بصيغة <family>:<action>، مثل vehicles:read. النطاق <family>:* يغطي كل إجراءات العائلة:
alerts:* يغطي alerts:read وalerts:write. الطلب الذي ينقصه نطاق العملية يتلقى 403 بالرمز
auth.token.scope_missing مع النطاقات الناقصة في detail.
يسرد مرجع الواجهة البرمجية كل نطاق وعدد العمليات التي تحتاج إليه، وتذكر صفحة كل عملية نطاقها.
التحقق الإضافي بخطوة MFA
إرسال أمر إلى جهاز والموافقة عليه (POST /v1/commands وPOST /v1/commands/{id}:approve) يحتاجان إلى تحقق
WebAuthn حديث. لا يصلح لذلك إلا رمز وصول OAuth من جلسة اجتازته؛ ولا يصلح مفتاح الواجهة أبدًا. دونه تجيب البوابة
بـ 403 والرمز step_up_required مع ترويسة WWW-Authenticate: Step-Up ….