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

المصادقة

كل عملية، عدا فهرس السوق، تحتاج إلى بيانات اعتماد في الترويسة 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 ….