المصادقة

يحمل كل طلب إلى واجهة Sursa API مفتاح API، أو رمز وصول OAuth لتطبيق، في الترويسة Authorization:

Authorization: Bearer kb_3f9c…

يحدد المفتاح المؤسسة، ويقرر ما يستطيع الطلب رؤيته وتغييره: دوره، ونطاقات صلاحياته، وملف تعريف البيانات الخاص به، ومجموعاته. لا جلسات ولا ملفات تعريف ارتباط على عنوان API. وكل طلب تجري مصادقته وحده، فيمكنك إرسال الطلبات بالتوازي ومن عدة خوادم بالمفتاح نفسه.

curl https://api.sursa.com/v1/me \
  -H "Authorization: Bearer $SURSA_API_KEY"

قد ترسل التكاملات الأقدم المفتاح في الترويسة X-API-Key بدلًا من ذلك. وهي لا تزال مقبولة، لكن على الشيفرة الجديدة استخدام Authorization: Bearer.

أنواع بيانات الاعتماد

بيانات الاعتماد	شكلها	أين تعمل
مفتاح API للمؤسسة	`kb_…`	كل نقاط نهاية واجهة API، في حدود دوره ونطاقاته وملف تعريف البيانات ومجموعاته.
مفتاح المصدر المخصص	`kbsrc_…`	نقاط نهاية الإرسال في المصدر المخصص الخاص به فقط (`/v1/push/sources/{source_id}/…`).
رمز وصول OAuth	`kbat_…`	نقاط نهاية مرجع API، في حدود نطاقات الرمز. الرمز الصادر من `POST /oauth/token` برمز تخويل يعمل نيابةً عن الموظف الذي أعطى الموافقة؛ أما رمز `client_credentials` فيعمل باسم المؤسسة، مثل مفتاح API. ومدة صلاحية الرمز ساعة واحدة.

تُرسَل كلها بالطريقة نفسها. ولا يستطيع مفتاح المصدر المخصص قراءة أي شيء خارج مصدره أو البحث فيه أو تغييره؛ استخدمه حيث يحفظ المفتاحَ طرفٌ ثالث، مثل منصة تكامل.

أخطاء المصادقة

الحالة والرمز	المعنى	ما العمل
`401` `auth.not_authenticated`	لا مفتاح، أو مفتاح مكتوب خطأً، أو مفتاح مُبطَل.	تحقّق من الترويسة ومن قيمة المفتاح.
`401` `api_keys.expired`	تجاوز المفتاح تاريخ انتهاء صلاحيته.	أنشئ مفتاحًا جديدًا واستبدل به القديم.
`401` `sources.push_key_invalid`	مفتاح المصدر المخصص خاطئ أو مُبطَل أو يخص مصدرًا آخر.	تحقّق من المفتاح ومن معرّف المصدر في المسار.
`401` `oauth.token_expired`	انتهت صلاحية رمز وصول OAuth.	احصل على رمز جديد برمز التحديث.
`403` `api_keys.scope`	ليس للمفتاح نطاق صلاحيات لهذه العملية.	أضف النطاق، أو استخدم مفتاحًا يملكه.
`403` `api_keys.feature_disabled`	خطة المؤسسة لا تشمل مفاتيح API.	تواصل مع مشرف المؤسسة.
`403` `api_keys.ip_not_allowed`	يأتي الطلب من عنوان خارج العناوين المسموح بها للمفتاح.	أرسل الطلب من شبكة مسموح بها، أو غيّر عناوين المفتاح.
`403` `api_keys.mcp_only`	استُخدم مفتاح MCP شخصي خارج نقطة النهاية `/mcp`.	استخدم مفتاح API للمؤسسة مع واجهة API.
`403` `oauth.operation_not_allowed`	العملية ليست جزءًا من واجهة API العامة، فلا يستطيع رمز OAuth استدعاءها.	استخدم عملية من مرجع API.
`403` `org.suspended`	المؤسسة معلّقة، وبياناتها محفوظة.	تواصل مع مشرف المؤسسة.

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

العمل بصفة ملف تعريف بيانات

يستطيع المفتاح ذو الدور admin أن يتحقق مما ستراه فئة أخرى من الناس: الترويسة X-View-As تنفّذ الطلب بصفة ملف تعريف بيانات، وبصفة دور أيضًا إن شئت.

curl "https://api.sursa.com/v1/cards?limit=20" \
  -H "Authorization: Bearer $SURSA_ADMIN_KEY" \
  -H "X-View-As: employee:viewer"

الطلبات في هذا الوضع تقرأ فقط: أي تغيير يعيد الحالة 403 مع الرمز view_as.read_only. ولا يستطيع رمز OAuth، ولا مفتاح بلا الدور admin، استخدام الترويسة X-View-As: يجيب الطلب بالحالة 403 مع الرمز view_as.admin_key_required. والترويسة التي لا تسمّي ملف تعريف موجودًا تجيب بالحالة 400 مع الرمز view_as.invalid_header.

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

تسمح واجهة API بالطلبات من أي أصل ويب (Access-Control-Allow-Origin: *) ولا تستخدم ملفات تعريف الارتباط أبدًا، فيمكن للصفحة استدعاؤها عبر fetch. وعندها يعيش المفتاح في الصفحة ويراه كل من يستخدمها. لا تستدعِ واجهة API من المتصفح إلا بمفتاح لا تمانع في أن يراه هؤلاء المستخدمون، مثل مفتاح بالدور viewer مقصور على مجموعات عامة، أو ضع خادمك الخاص بين المتصفح وSursa.

ما لا يستطيعه إلا الموظف

يعمل مفتاح API للمؤسسة باسم المؤسسة، لا باسم شخص. وفي واجهة API جزءان يخصّان الأشخاص، فلا يعملان إلا برمز يعمل نيابةً عن موظف: جلسة في Sursa، أو رمز وصول OAuth صادر بموافقة الموظف.

المحادثات تخص الشخص. لا يرى مفتاح API للمؤسسة في GET /v1/conversations إلا المحادثات التي بدأها هو نفسه. وليس في واجهة API العامة عملية تبدأ محادثة، لذلك تكون القائمة فارغة عادةً بالنسبة إلى المفتاح، ولا تُعرض له محادثات الموظفين أبدًا. أما الأسئلة خارج المحادثة، عبر POST /v1/ask أو POST /v1/chat، فتعمل بأي مفتاح له النطاق ask. ولعرض محادثات موظف وقراءة سجل إحداها عبر GET /v1/conversations/{conv_id}، استدعِ واجهة API برمز OAuth نيابةً عن ذلك الموظف. لا يرى الرمز إلا محادثات ذلك الموظف نفسه؛ وأي محادثة أخرى تجيب بالحالة 404 مع الرمز conversations.not_found.

لا يوثّق البطاقة إلا موظف. يؤكد التوثيق أن شخصًا راجع المحتوى، لذلك تحتاج العمليتان POST /v1/cards/{card_id}/verification/verify وPOST /v1/cards/{card_id}/verify إلى جلسة أو رمز OAuth نيابةً عن موظف يحق له توثيق البطاقة. ومع مفتاح API للمؤسسة، أو رمز client_credentials، تجيبان بالحالة 400 مع الرمز cards.verify_user_account_required. وتأتي الفحوص المعتادة أولًا: البطاقة التي لا يراها المفتاح تجيب بالحالة 404، والمفتاح غير المسموح له بتوثيقها يتلقى الحالة 403.