الانتقال إلى المحتوى الرئيسي
عندما تنشئ أو تقرأ مفتاح API عبر وحدة التحكم أو REST API، تعيد البوابة كائن رمز — سجل JSON الذي يحمل هوية مفتاح وحدوده والربطين بالسياسة اللذين يحكمان حركة مروره. هذه الصفحة هي المرجع حقلاً بحقل لذلك الكائن: ماذا يعني كل حقل، ونوعه، والقيم العلامية (0، -1) التي تحمل معنى خاصاً. لمعرفة لماذا وراء هذه الحقول — نموذج الاستقلالية الأدنى — ابدأ بـ نظرة عامة على المفاتيح المحددة النطاق. هذه الصفحة هي جدول البحث الذي تبقيه مفتوحاً بينما تكتب برمجة إنشاء المفاتيح.

​
1. مرجع كائن الرمز بلمحة

يبدو مفتاح أُنشئ حديثاً لوكيل تلخيص مجدوَل هكذا: 
{
  "id": 4812,
  "name": "support-summarizer-prod",
  "status": 1,
  "key": "sk-orca-a1b2****yz90",
  "created_time": 1733616000,
  "accessed_time": 1733702400,
  "expired_time": -1,
  "unlimited_quota": false,
  "remain_quota": 500000,
  "used_quota": 12340,
  "model_limits_enabled": true,
  "model_limits": "openai/gpt-4o-mini",
  "credit_limit_usd": 25,
  "allow_ips": "203.0.113.7",
  "environment": "prod",
  "guardrail_id": 17,
  "firewall_policy_id": 9,
  "is_firewall_gateway": false,
  "group": "default"
}
حقل key مُخفى في كل قراءة — ترى بادئة العلامة التجارية والأحرف الأربعة الأخيرة، لا السرّ الكامل أبداً. يُعرض النص الصريح مرة واحدة، عند الإنشاء. انظر إخفاء المفتاح.

​
2. حقول الهوية ودورة الحياة

تصف أي مفتاح هذا وأين هو في دورة حياته.
المُعرِّف الرقمي المستقر للمفتاح. استخدمه لمخاطبة المفتاح في استدعاءات التحديث والحذف. للقراءة فقط.
وسم بشري للمفتاح، يُعرض في وحدة التحكم وفي السجلات. سمِّ المفاتيح باسم الوكيل الذي يحملها — مفتاح واحد، وكيل واحد.
حالة مفعّل / معطّل. 1 يعني نشطاً؛ مفتاح معطّل يُرفض عند المصادقة دون حذفه، فيمكنك إيقاف مفتاح مؤقتاً وإعادة تفعيله.
السرّ الحامل، يُعاد مُخفىً (sk-orca-…****…). القيمة الكاملة تُعرض مرة واحدة فقط، عند الإنشاء. عامِله مثل كلمة مرور.
طوابع زمنية بصيغة Unix (ثوانٍ) لوقت سكّ المفتاح ووقت آخر خدمة طلب. accessed_time هو إشارتك لمفتاح قديم أو غير مستخدم يستحق الإلغاء.
صلاحية انتهاء مطلقة كطابع زمني Unix. العلامة -1 تعني أن المفتاح لا ينتهي أبداً. اضبط طابعاً زمنياً حقيقياً لجعل مفتاح ينتهي تلقائياً — الافتراضي الصحيح لتشغيلات CI والوكلاء الزائلين. انظر المفاتيح المنتهية الصلاحية.

​
3. حقول الإنفاق والحصة

تحدّ كم يمكن لمفتاح أن يستهلك قبل أن يتوقف عن العمل.
الحقلالنوعالمعنى
credit_limit_usdnumberسقف الإنفاق مدى الحياة بالدولار. 0 = بلا حدود.
unlimited_quotabooleanعندما يكون true، لا يُقاس المفتاح مقابل رصيد حصة.
remain_quotanumberالحصة المتبقية على المفتاح.
used_quotanumberالحصة المستهلَكة حتى الآن.
مفتاح بـ credit_limit_usd: 0 و unlimited_quota: true و expired_time: -1 ليس له سقف إنفاق ولا ينتهي أبداً — أسوأ نطاق انفجار إذا تسرّب. انظر غير محدود مقابل محدود لمعرفة متى يكون مفتاح غير محدود مبرَّراً.

​
4. حقول الوصول والنطاق

تحدّ ما يمكن للمفتاح الوصول إليه — أي النماذج، من أي عناوين.
model_limits هو قائمة النماذج التي يجوز للمفتاح استدعاؤها؛ model_limits_enabled هو مفتاح التشغيل / الإيقاف. مع تفعيل الحدّ، يُرفض أي استدعاء لنموذج خارج القائمة قبل أن يغادر البوابة — لا يستطيع الوكيل التحوّل إلى نموذج أغلى أو أكثر قدرة. انظر حدود النماذج.
قائمة سماح IP / CIDR، إدخال واحد لكل سطر. طلب يقدّم المفتاح من أي عنوان غير مُدرَج يُرفض في طبقة المصادقة؛ وقيمة فارغة تعني أن كل العناوين مسموحة. انظر قائمة سماح IP.
وسم نشر حرّ (prod، staging، dev، أو أي شيء تختاره) لتنظيم المفاتيح وتصفية السجلات. تنظيمي بحت — لا يغيّر الفرض. انظر البيئات.
مجموعة التوجيه التي يحلّ المفتاح النماذج خلالها. اتركها على افتراضي مساحة العمل ما لم تُعطَ مجموعة محددة.

​
5. حقول ربط السياسة

أقوى حقلين على مفتاح. كلٌّ يربط المفتاح بسياسة ضمن نطاق مساحة العمل تحكم حركة مروره — غيّر السياسة وكل مفتاح مرتبط بها يلتقط التغيير في الطلب التالي، دون إعادة نشر.
الحقلالنوعيربط المفتاح بـ
guardrail_idnumberحاجز حماية محتوى يفحص نص الطلب والاستجابة.
firewall_policy_idnumberسياسة جدار حماية تحكم استدعاءات الأدوات التي يصدرها المفتاح.
is_firewall_gatewaybooleanيعلّم المفتاح كرمز ضمن نطاق البوابة لمسارات Firewall MCP / evaluate (وليس للاستدلال).
العلامة لكلا الربطين هي 0 (غير مرتبط). لكن المستويين يحلّان ربطاً معطّلاً بشكل مختلف:
  • guardrail_id معطّل هو مفتاح الإطفاء — يحصل المفتاح على لا حاجز حماية، دون تراجع إلى افتراضي مساحة العمل.
  • firewall_policy_id معطّل يتراجع إلى سياسة جدار الحماية الافتراضية لمساحة العمل.
ترتيب الحل الكامل يعيش على ربط السياسات و النطاق والمفاتيح.
is_firewall_gateway: true يسكّ مفتاحاً ضمن نطاق البوابة لمسارات /api/v1/firewall/* فقط — لا تضعه أبداً على مفتاح استدلال. تفعيل العلامة، وقراءة النص الصريح لمفتاح بوابة، يتطلبان كلاهما Admin+.

​
6. ضبط هذه الحقول

كل حقل أعلاه يُضبَط في محرّر مفاتيح وحدة التحكم (/console/token) — وليس عبر مفتاح ترحيل. إنشاء مفتاح أو تعديله يتطلب دور Developer أو أعلى؛ وعلامة is_firewall_gateway تتطلب Admin+.
كائن الرمز هو سطح الإعداد. النص الصريح للمفتاح (sk-orca-…) هو ما يقدّمه وكيلك على استدعاءات الترحيل /v1/*. اضبط المفتاح في وحدة التحكم؛ الوكيل لا يرى أبداً سوى السرّ.
مفتاح ملموس بأدنى استقلالية — مضبوط في المحرّر، مقروء كالكائن أعلاه — يحدّ نموذجاً واحداً، ونطاق IP مصدري واحداً، وسقفاً أسبوعياً بالدولار، وصلاحية، وحاجز حماية واحداً زائد سياسة جدار حماية واحدة. إذا اختُطف الوكيل الذي يحمله عبر حقن المطالبة، يتوقف نطاق الانفجار عند تلك الحدود بالضبط.

​
7. مراجع ذات صلة

نظرة عامة على المفاتيح المحددة النطاق

نموذج الاستقلالية الأدنى والمحطة المركزية لكل حقل مفتاح.

ربط السياسات

كيف يُحَل guardrail_id وfirewall_policy_id إلى سياسة نشطة.

الحصة والسقف والصلاحية

credit_limit_usd، expired_time، وحقول الحصة بالعمق.

قائمة تحقّق الاستقلالية الأدنى

مرّر كل مفتاح عبر نفس مرحلة التقسية.
جديد على النموذج؟ اقرأ النطاق والمفاتيح والسياسات ومساحات العمل لمعرفة كيف يلائم كائن الرمز تسلسل مساحة العمل ← السياسة ← المفتاح.