مفاتيح API ونطاقات الصلاحيات

كل طلب إلى واجهة Sursa API يُرسَل بمفتاح API من مفاتيح مؤسستك. ويتبع المفتاح المؤسسة لا شخصًا بعينه: يبقى عاملًا حين يغادر الموظف الذي أنشأه، وما يستطيع فعله يُضبط على المفتاح نفسه.

ما يُسمح للمفتاح بفعله

ثلاثة إعدادات للمفتاح تقرر ما يستطيع الطلب به أن يراه ويغيّره. وكل إعداد منها لا يفعل إلا أن يضيّق ما يسمح به الآخران.

ويمكن أيضًا قصر المفتاح على بعض المجموعات وتحديد تاريخ انتهاء صلاحيته. والطلب خارج هذه الحدود يفشل: النطاق الناقص يعيد الحالة 403 مع الرمز api_keys.scope، والكائن الذي لا يستطيع المفتاح رؤيته يعيد 404، تمامًا كأنه غير موجود.

امنح كل تكامل مفتاحه الخاص بأضيق دور ونطاقات صلاحيات يحتاج إليها. فمهمة المزامنة التي تكتب المستندات فقط لا تحتاج إلى admin، ومهمة التقارير لا تحتاج إلى نطاقات الكتابة.

إنشاء مفتاح

ينشئ مشرف المؤسسة المفاتيح في Sursa من Administration → API keys (الإدارة ← مفاتيح API)، أو بالعملية POST /v1/api-keys باستخدام مفتاح أو جلسة لها الدور admin:

curl -X POST https://api.sursa.com/v1/api-keys \
  -H "Authorization: Bearer $SURSA_ADMIN_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CRM sync",
    "role": "editor",
    "expires_at": "2027-06-30T00:00:00Z"
  }'

تحتوي الاستجابة قيمة المفتاح في الحقل key. وهي تُعرض مرة واحدة: لا يحفظ Sursa سوى قيمة تجزئة لها (hash)، ولا يستطيع عرضها مرة أخرى. يبدو المفتاح على شكل kb_ يليها 43 حرفًا؛ وتُعرض أحرفه الأولى (prefix) في قائمة المفاتيح لتميّز المفاتيح بعضها من بعض.

بلا scopes يحصل المفتاح على نطاقات دوره. مرّر scopes لتضييقها أكثر. وبلا expires_at لا تنتهي صلاحية المفتاح.

حفظ المفاتيح سرًا

• احفظ المفاتيح في مدير أسرار أو في متغيرات البيئة لخدمتك، لا في الشيفرة المصدرية أبدًا.
• استخدم المفاتيح من خوادمك فقط. يقبل Sursa الطلبات من المتصفحات (CORS مفتوح)، لكن المفتاح في صفحة ويب يراه كل من يفتحها.
• لا ترسل المفتاح أبدًا في عنوان URL. أرسله في الترويسة Authorization فقط.
• إذا تسرّب مفتاح، فأبطله فورًا وأنشئ مفتاحًا جديدًا.

التحقق من المفتاح

تعيد العملية GET /v1/me المفتاح ودوره ونطاقاته الفعلية وملف تعريف البيانات وتاريخ انتهاء الصلاحية وحد المعدل. وهي تعمل مع أي مفتاح صالح، أيًّا كانت نطاقاته، فاستخدمها لاختبار اتصال تكاملك وحين تتحرى سبب الحالة 403.

تدوير المفتاح

التدوير يستبدل المفتاح دون إيقاف التكامل. وأسرع طريقة هي إعادة إصدار المفتاح: تصدر العملية POST /v1/api-keys/{key_id}/roll قيمة جديدة للمفتاح نفسه، بالدور ونطاقات الصلاحيات والمجموعات وتاريخ انتهاء الصلاحية نفسها. وتظل القيمة السابقة تعمل مدة overlap_hours (24 ساعة افتراضيًا، وحتى 168 ساعة)، فيمكنك نشر القيمة الجديدة في الأثناء؛ وتنهي العملية POST /v1/api-keys/{key_id}/revoke-previous فترة التداخل مبكرًا.

أما لاستبدال المفتاح بمفتاح آخر مختلف:

1. أنشئ مفتاحًا جديدًا بالدور ونطاقات الصلاحيات وملف تعريف البيانات نفسها.
2. انشر المفتاح الجديد في تكاملك.
3. راقب المفتاح القديم في Administration → API keys (أو الحقل last_used في GET /v1/api-keys) حتى يتوقف استخدامه.
4. أبطل المفتاح القديم.

حدّد تاريخ انتهاء صلاحية للمفاتيح ودوّرها قبله. ينبّه Sursa مشرفي المؤسسة قبل انتهاء صلاحية المفتاح؛ والمفتاح المنتهي الصلاحية يعيد الحالة 401 مع الرمز api_keys.expired.

إبطال المفتاح

أبطل المفتاح من Administration → API keys أو بالعملية DELETE /v1/api-keys/{key_id}. ويسري الإبطال خلال ثوانٍ على كل خوادم API. والطلبات بمفتاح مُبطَل تعيد الحالة 401 مع الرمز auth.not_authenticated.

مفاتيح المصدر المخصص

لكل مصدر مخصص نوع خاص من المفاتيح. يبدأ بالبادئة kbsrc_، ولا يستطيع إلا كتابة المستندات في ذلك المصدر الواحد، ولا يستطيع قراءة أي شيء أو البحث فيه. وهو أكثر المفاتيح أمانًا لتعطيه منصة تكامل مثل Zapier. أنشئه في صفحة المصدر من API keys (مفاتيح API للمصدر) أو بالعملية POST /v1/sources/{source_id}/push-keys.

حين لا تتوفر المفاتيح

مفاتيح API جزء من خطة المؤسسة. وإذا لم تشملها الخطة، فإن إنشاء مفتاح وكل طلب بمفتاح يعيدان الحالة 403 مع الرمز api_keys.feature_disabled.