الموارد · المصادقة

توثيق المصادقة والنطاق

دليل إنتاجي كامل لمصادقة JWT/session و API key وهيدرز النطاق وسياق مساحة العمل وقواعد التحقق.

طرق المصادقة

  • مصادقة JWT/session للطلبات المرتبطة بسياق المستخدم.
  • مصادقة API key للتكاملات بين الخدمات والتحكم المؤسسي.

الهيدرز المطلوبة

Authorization: Bearer [jwt_token] أو X-API-Key: [api_key]Content-Type: application/jsonX-Scope-Type: personal | workspaceX-Workspace-ID: مطلوب فقط في نطاق workspace

نموذج النطاق

  • النطاق الشخصي يعمل تحت سياق المستخدم المصادق عليه.
  • نطاق مساحة العمل يعمل تحت Workspace محدد مع صلاحيات حسب الدور.

قواعد التحقق

  • إذا كان النطاق personal فلا يجب إرسال X-Workspace-ID.
  • إذا كان النطاق workspace فـ X-Workspace-ID إلزامي.
  • الهيدرز المتضاربة أو غير الصحيحة تعيد 422.

مثال مصادقة JWT

bash
curl -X POST "/api/v1/chat/completions" \
  -H "Authorization: Bearer [jwt_token]" \
  -H "Content-Type: application/json" \
  -H "X-Scope-Type: personal" \
  -d '{
    "message":"Hello from JWT auth",
    "stream":false
  }'

مثال مصادقة API Key

bash
curl -X POST "/api/v1/chat/completions" \
  -H "X-API-Key: [api_key]" \
  -H "Content-Type: application/json" \
  -H "X-Scope-Type: workspace" \
  -H "X-Workspace-ID: [workspace_uuid]" \
  -d '{
    "message":"Hello from API key auth",
    "stream":false
  }'

نطاق مساحة العمل

json
{
  "headers": {
    "X-Scope-Type": "workspace",
    "X-Workspace-ID": "[workspace_uuid]"
  },
  "note": "Workspace scope requires workspace id."
}

النطاق الشخصي

json
{
  "headers": {
    "X-Scope-Type": "personal"
  },
  "note": "Personal scope must not include workspace id."
}

نماذج الأخطاء

401

المصادقة مفقودة أو منتهية أو غير صحيحة.

403

النطاق غير مسموح أو يوجد تقييد صلاحيات داخل مساحة العمل.

422

فشل التحقق من الهيدرز أو السياق.

429

تم تجاوز حد المعدل حسب سياق المصادقة الحالي.