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

يسمّي نطاق الصلاحيات جزءًا من واجهة API يحق للمفتاح استدعاؤه. وتعلن كل نقطة نهاية في مرجع API النطاق الواحد الذي تحتاج إليه. والطلب بمفتاح يفتقر إليه يُرفض بالحالة 403 والرمز api_keys.scope، قبل قراءة أي شيء أو تغييره.

تحدد النطاقات العمليات التي يحق للمفتاح استدعاؤها. أما الكائنات التي تراها هذه العمليات فيبقى تحديدها لدور المفتاح وملف تعريف البيانات والمجموعات: المفتاح الذي له النطاق cards:write والدور viewer لا يستطيع تغيير البطاقات، والمفتاح المقصور على مجموعة واحدة لا يرى المجموعات الأخرى.

النطاقات

النطاق	ما يسمح به
`cards:read`	قراءة البطاقات والمجموعات والمجلدات.
`cards:write`	إنشاء البطاقات والمجموعات والمجلدات وتغييرها وحذفها.
`search`	البحث في قاعدة المعرفة (`POST /v1/search`).
`ask`	سؤال المساعد (`POST /v1/ask` و`POST /v1/chat`).
`import:write`	الكتابة في المصادر المخصصة للمؤسسة: المزامنات والدفعات وعمليات الحذف، وقراءة حالتها. ويتطلب إنشاء مصدر ومفاتيحه الدور `admin`.
`webhooks:manage`	إدارة خطافات الويب وقراءة سجل الأحداث (`GET /v1/webhook-events`). ويتطلب كلاهما أيضًا الدور `admin`.
`users:read`	قراءة المستخدمين ومجموعات المستخدمين.
`users:write`	تغيير المستخدمين ومجموعات المستخدمين.
`analytics:read`	قراءة التحليلات.
`audit:read`	قراءة سجل التدقيق.
`finance:read`	قراءة التقارير المالية والفواتير والدفعات.
`catalog:read`	قراءة دليل الخدمات.
`files:read`	قراءة الملفات المولَّدة، مثل الإجابات المصدَّرة.
`files:write`	تغيير الملفات المولَّدة وحذفها.
`permissions:manage`	إسناد الصلاحيات على الكائنات وسحبها.
`admin`	إعدادات المؤسسة ومفاتيح API الخاصة بها. والمفتاح الذي له `admin` يملك كل النطاقات الأخرى أيضًا.

البحث والأسئلة قراءة بطبيعتها: المفتاح الذي يقتصر على القراءة يستطيع أيضًا أن يبحث ويسأل.

اختيار النطاقات

امنح التكامل النطاقات التي يستخدمها فقط، لا أكثر:

التكامل	النطاقات
روبوت أسئلة وأجوبة في أداة محادثة	النطاقان `search` و`ask`
الاستيراد من نظام المستندات لديك	النطاق `cards:write` (واجهة البطاقات) أو `import:write` (مصدر مخصص)
التصدير إلى مستودع البيانات	النطاقان `cards:read` و`users:read`، والنطاق `webhooks:manage` لسجل الأحداث
إنشاء حسابات المستخدمين من نظام الموارد البشرية لديك	النطاق `users:write`

مرّر القائمة عند إنشاء المفتاح:

curl -X POST https://api.sursa.com/v1/api-keys \
  -H "Authorization: Bearer $SURSA_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Support bot", "role": "viewer", "scopes": ["search", "ask"]}'

النطاقات السابقة

المفاتيح التي أُنشئت قبل تقسيم النطاقات تبقى عاملة. ونطاقاتها read وwrite وadmin تعني ما يلي:

النطاق السابق	المعنى
`read`	النطاقات `cards:read`، و`search`، و`ask`، و`users:read`، و`analytics:read`، و`finance:read`، و`catalog:read`، و`files:read`
`write`	كل ما في `read`، ومعه `cards:write` و`files:write` و`users:write` و`permissions:manage`
`admin`	كل النطاقات

المفتاح الذي أُنشئ دون نطاقات صريحة يأخذها من دوره: الدور admin يأخذ admin، والدوران editor وverifier يأخذان write، والدور viewer يأخذ read.

معرفة نطاقات المفتاح

تعيد العملية GET /v1/me نطاقات المفتاح الذي يرسل الطلب، أيًّا كانت نطاقاته. وللمفتاح المنشأ بلا نطاقات صريحة، هذه هي النطاقات السابقة لدوره، مثل read وwrite؛ ويبيّن الجدول أعلاه ما تعنيه. وحين تفشل عملية بالرمز api_keys.scope، يذكر الحقل error.message النطاق الناقص.