API Keys
API key للمطور هي بيانات الاعتماد التي يقدّمها كودك في كل طلب. تُنشأ keys وتُدار في لوحة الإدارة — لا عبر الواجهة نفسها — وتحمل كل key بيئة، ومجموعة scopes، وسرًّا يُكشف مرة واحدة فقط.
أين تُدار keys
تقع إدارة keys في وحدة تحكم المطور داخل اللوحة على /org/developer-api. إنشاء وعرض وتدوير وإلغاء keys هي إجراءات إدارية تُنفَّذ هناك بجلستك العادية المسجَّل دخولها — وهي عمدًا ليست جزءًا من سطح /v1 المُصادَق عليه بـ cuk_ (لا يمكن لـ key مسرّبة أبدًا أن تُنشئ أو تُلغي key أخرى). تتوفر وحدة التحكم على Starter وما فوق؛ ولا يمكن لـ organizations في trial إنشاء keys.
صيغة الـ key
يأخذ سر الـ key الصيغة cuk_<env>_<random> — على سبيل المثال:
cuk_live_M8s2k...<random>ويتكوّن من ثلاثة أجزاء:
| الجزء | المعنى |
|---|---|
cuk | بادئة العلامة — تبدأ كل key من Cuneiform Chat بـ cuk_. |
<env> | البيئة: live أو test. |
<random> | سر عشوائي طويل وآمن للـ URL. |
البيئات
تُنشأ كل key لبيئة واحدة:
| البيئة | البادئة | الاستخدام |
|---|---|---|
live | cuk_live_ | حركة الإنتاج على بياناتك الحقيقية. |
test | cuk_test_ | التطوير واختبار التكامل. |
الكشف لمرة واحدة
يُعرَض السر الكامل مرة واحدة بالضبط — في اللحظة التي تُنشئ فيها key أو تدوّرها. بعد ذلك، تُعرَض فقط بادئة الـ key (cuk_<env>_) وأحرفها الأربعة الأخيرة، لتتمكن من التعرّف على key في قائمة دون أن تكون قابلة للاسترجاع.
إذا فقدت سرًّا، فلا يمكنك استرجاعه — دوّر الـ key للحصول على سر جديد (وهذا يلغي السر القديم)، أو ألغِها وأنشئ واحدة جديدة.
Scopes
تُمنَح الـ key مجموعة فرعية من خمسة scopes. يفتح كل scope مجموعة من العمليات، ويُقيَّد إضافيًا بأذونات RBAC للدور الذي أنشأ الـ key — لا يمكن لـ key أبدًا أن تمنح أكثر مما يملكه منشئها في اللوحة.
| Scope | ما يفتحه | سقف RBAC |
|---|---|---|
knowledge:read | عرض وبحث وجلب المستندات والمجلدات وtags. | يتطلب إذن read للمحتوى. |
knowledge:write | رفع وحذف وتنظيم المستندات؛ إنشاء/تحديث/حذف المجلدات وtags. | يتطلب إذنَي upload + update للمحتوى. |
agents:read | عرض وجلب agents وضبطها. | يتطلب إذن read لـ agent. |
agents:write | إنشاء وتحديث agents؛ تحديث الضبط؛ الحذف والاستعادة. | يتطلب إذنَي create + update لـ agent (يتطلب الحذف/الاستعادة أيضًا إذن حذف agent). |
agents:query | تشغيل agent (POST /agents/{id}/query). | يتطلب إذن read لـ agent. |
امنح key فقط الـ scopes التي تحتاجها. يُرفَض أي طلب يستدعي endpoint خارج scopes الخاصة به بالرمز 403 permission_error (invalid_scope).
إدارة keys (في وحدة التحكم)
تدعم وحدة تحكم المطور على /org/developer-api:
- الإنشاء — اختر بيئة وscopes؛ يُكشف السر مرة واحدة.
- العرض — اطّلع على بادئة كل key وأحرفها الأربعة الأخيرة وscopes وحالتها (لا يُعرَض السر مرة أخرى أبدًا).
- التدوير — أنشئ سرًّا جديدًا لـ key وألغِ السابق. استخدم هذا وفق جدول روتيني أو فورًا إذا كان من الممكن أن تكون key قد تسرّبت.
- الإلغاء — عطّل key بشكل دائم. تُرفَض الطلبات التي تقدّم key ملغاة بالرمز
401.
لا يوجد أي endpoint للواجهة لأيٍّ من هذه الإجراءات — فهي مقصورة على اللوحة بحكم التصميم.