تحقق من المفتاح (Key)

GET /ping هو النداء الأول المعتمد تجاه واجهة REST للمطوّرين: فهو يؤكّد أن المفتاح يعمل ويُبلّغ بالضبط بما يمكنه فعله. نفّذ هذا النداء فور إنشاء مفتاح للتحقق من بيانات الاعتماد قبل البناء على نقاط نهاية الموارد.

GET /ping

يتحقق من بيانات الاعتماد المُنادِية ويُبلّغ بسياق واجهة المطوّر الذي تتحلّل إليه. يعيد 200 مع السياق الذي تم التحقق منه، أو 401 إذا كان المفتاح مفقودًا أو مشوّهًا أو ملغى أو غير معروف.

Scope: لا شيء — أي مفتاح صالح (أو جلسة مسجَّلة الدخول) · النجاح: 200

على عكس كل نقطة نهاية للموارد، فإن /ping ليس مقيَّدًا بـ scope. يمكن لمفتاح يحمل أي scope مفرد — حتى knowledge:read فقط — أن يستدعيه للتحقق من نفسه. هذا هو الهدف: يجب أن تكون قادرًا على تأكيد أن المفتاح يعمل بغضّ النظر عمّا يُسمح له بفعله.

curl https://cuneiform.chat/api/developer/v1/ping \
  -H "Authorization: Bearer cuk_live_xxxxxxxxxxxxxxxx"

يعيد الطلب المُصادَق عليه بمفتاح المؤسسةَ التي يعمل المفتاح نيابةً عنها، والدور المُصادَق عليه، وكيف صادقتَ، إضافةً إلى معرّف المفتاح المُنادِي واسمه وآخر أربعة أحرف منه والصلاحيات (scopes) الممنوحة له:

{
  "object": "developer_api_context",
  "organization": {
    "id": "org_8s2k1d",
    "name": "Acme Inc"
  },
  "role": "owner",
  "authenticated_via": "api_key",
  "api_key": {
    "id": "key_4f9a2c",
    "name": "Production CI",
    "last4": "ab12",
    "scopes": ["agents:read", "agents:query", "knowledge:read"]
  }
}

مصفوفة scopes هي بالضبط المجموعة الممنوحة للمفتاح — استخدمها للتأكد من أن المفتاح يملك الوصول الذي يحتاجه تكاملك قبل الاعتماد عليه.

الأخطاء: 401، 429، 500.

ماذا تُخبرك الاستجابة

ما لا تعيده أبدًا

الاستجابة deny-by-default: فهي مبنية فقط من سياق الطلب الذي تم التحقق منه، لذا لا يمكنها أبدًا إعادة بيانات مؤسسة أخرى ولا تكشف حقلًا داخليًا للمفتاح. السرّ الكامل للمفتاح، و hash البحث، والمنشئ، والمعرّف الداخلي الخام، وصلاحيات RBAC الأساسية للدور لا تظهر أبدًا — فقط حقول المفتاح الأربعة أعلاه.

متى تفشل

يعيد المفتاح المفقود أو المشوّه أو الملغى أو غير المعروف 401 مع مغلّف الخطأ القياسي:

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "The API key is missing or invalid."
  }
}

بما أن /ping غير مقيَّد بـ scope، فهو لا يعيد أبدًا 403 لسبب متعلق بـ scope — فالرمز 401 يعني أن بيانات الاعتماد نفسها غير صالحة.