DuoKey Cockpit — نظرة عامة على API
كل ما تحتاجه لاستدعاء واجهة برمجة تطبيقات Cockpit: عناوين URL الأساسية، والمصادقة، وتعدد المستأجرين، والأذونات، والاصطلاحات، والأخطاء.
واجهتا HTTP
يوفّر Cockpit نوعين من واجهات HTTP:
| الواجهة | المسار الأساسي | الجهة المستدعية |
|---|---|---|
| واجهة الإدارة (Management API) | /api/… | تكاملاتك ووحدة تحكم Cockpit — تتم المصادقة عليها برمز حامل (bearer token) |
| نقاط نهاية البروتوكول العام | مسارات جذرية مثل /dke/…، /ocsp/…، /scep/…، .well-known/est/… | عملاء قياسيون يتحدثون بروتوكولاً عاماً (Microsoft 365، عملاء ACME/EST/SCEP/CMP، مستجيبات OCSP) |
عنوان URL الأساسي هو مضيف Cockpit الخاص بك، على سبيل المثال https://cockpit.example.com. تستخدم جميع الأمثلة أدناه مسارات نسبية إلى هذا المضيف.
المصادقة
تحمل طلبات واجهة الإدارة (Management API) رمزاً حاملاً (bearer token) في ترويسة Authorization:
Authorization: Bearer <access-token>
راجع المصادقة لمعرفة كيفية الحصول على رمز وكيفية عمل الجلسات. تستخدم نقاط نهاية البروتوكول العام آلية المصادقة التي يحددها معيارها الخاص (مثل رمز Azure AD لطلبات فك تشفير DKE، أو مفاتيح حساب ACME).
تعدد المستأجرين
يعمل كل طلب ضمن السياق الأمني لـ المستأجر (tenant) المُشفَّر داخل الرمز — فأنت لا تمرر معرّف مستأجر أبداً بشكل صريح، ولا يمكنك رؤية أو تعديل سوى بيانات مستأجرك الخاص. بعض نقاط النهاية الإدارية هي على مستوى المضيف (host-level) (عابرة للمستأجرين) وتتطلب رمز مضيف (host token)؛ وهذه مذكورة في صفحة إدارة المنصة.
الأذونات
تخضع الإجراءات لبوابة أذونات قائمة على الأدوار (role-based permissions). يجب أن يمتلك المتصل الإذن الذي يتطلبه المسار (مثل إذن إصدار الشهادات لإصدار شهادة). تُجمَّع أسماء الأذونات حسب المجال (عمليات المنصة، PKI، إدارة المضيف، وما إلى ذلك) وتُدرَج لكل نقطة نهاية في كل صفحة API.
الاصطلاحات
| الجانب | الاصطلاح |
|---|---|
| التنسيق | نصوص الطلب والاستجابة بصيغة JSON؛ ترميز UTF-8 |
| المعرّفات | معرّفات الموارد هي UUID |
| الطرق (Methods) | REST قياسي: GET (قراءة)، POST (إنشاء/إجراء)، PUT/PATCH (تحديث)، DELETE (حذف) |
| الطوابع الزمنية | ISO 8601 (بتوقيت UTC) |
| ترويسة المصادقة | Authorization: Bearer <token> |
نموذج الأخطاء
تُعيد الأخطاء حالة HTTP غير 2xx مع نص JSON يصف المشكلة. الحالات الشائعة:
| الحالة | المعنى |
|---|---|
| 400 Bad Request | طلب مشوَّه أو فشل في التحقق من الصحة |
| 401 Unauthorized | رمز مفقود أو غير صالح |
| 403 Forbidden | تمت المصادقة لكن دون امتلاك الإذن المطلوب (أو الميزة غير مفعّلة لهذا الإصدار) |
| 404 Not Found | لا يوجد مورد كهذا في مستأجرك |
| 409 Conflict | تعارض في الحالة (مثل اسم مستخدَم بالفعل) |
| 429 Too Many Requests | تجاوز حد المعدل |
أقسام API
المصادقة
الحصول على رمز وفهم الجلسات
واجهة الخزائن والمفاتيح (Vaults & Keys API)
إدارة الخزائن ومادة المفاتيح
واجهة الإدارة التنظيمية (Administration API)
المستخدمون، الأدوار، الوحدات التنظيمية، موفّرو الهوية، سياسات الوصول
واجهة إدارة المنصة (Platform Administration API)
على مستوى المضيف: المستأجرون، إعدادات المضيف، الإصدارات، الميزات
واجهة DKE (DKE API)
إدارة خدمات DKE وبروتوكول GetKey / Decrypt العام
واجهة PKI (PKI API)
سلطات الشهادات، الشهادات، CRL/OCSP، المُصدرون، بروتوكولات التسجيل، النشر