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

​
1. لماذا تدوّر، ولماذا لا في مكانه أبداً

المفتاح على OrcaRouter هوية ثابتة، لا مجرد سلسلة — يحمل قائمة سماح نماذجه، وقائمة سماح IP، وسقف إنفاقه، وصلاحيته، و ربط سياساته. لا يمكنك تغيير المادة السرية لمفتاح موجود؛ تُصدَر بيانات الاعتماد والقيود معاً عند الإنشاء. لذا “التدوير” يعني إصدار خلَف والترحيل إليه. افعله:
  • على وتيرة ثابتة لأي بيانات اعتماد إنتاجية (الربع سنوي خط أساس شائع)؛
  • لحظة الاشتباه في تسرّب مفتاح — رغم أنه لتسرّب مؤكد، اقطعه أولاً ودوّر ثانياً (انظر الاستجابة للمفتاح المسرّب)؛
  • كلما تغيّر مالك المفتاح (موظف، تكامل مورّد، وكيل خارج من الخدمة).
النص الصريح (sk-orca-…) يُعرض مرة واحدة، عند الإنشاء — انسخه حينها. بعد ذلك تعرض وحدة التحكم شكلاً مُخفىً فقط مثل orca-7Bf****wxyz. يمكن لـ Developer+ إعادة كشف النص الصريح لمفتاح عادي لاحقاً، لكن مفتاحاً ضمن نطاق البوابة (is_firewall_gateway) يتطلب Admin لقراءة نصه الصريح مجدداً — فعامِل أول كشف لمفتاح البوابة كنسختك الموثوقة الوحيدة.

​
2. تسلسل تدوير مفتاح api

الهدف كله تداخل نظيف: المفتاح الجديد يعمل قبل أن يتوقف القديم. أربع خطوات.
1

أنشئ المفتاح الخلَف

اسكّ مفتاحاً جديداً بـ نفس النطاق للذي تستبدله — نفس model_limits، allow_ips، credit_limit_usd، expired_time، ونفس guardrail_id / firewall_policy_id. انسخ النص الصريح فوراً. التدوير هو اللحظة المثالية لـ تشديد النطاق أيضاً: أسقط نموذجاً لم يعد الوكيل يستخدمه، أو ضيّق قائمة سماح IP.
2

انقل حركة المرور

انشر sk-orca-… الجديد إلى كل مستدعٍ — الإعداد، مدير الأسرار، متغيّر CI، بيئة تشغيل الوكيل. أطلقه بنفس طريقة شحنك أي تغيير سرّ. كلا المفتاحين حيّان عند هذه النقطة، فيمكن تنظيم عمليات النشر بالتدرّج دون عطل.
3

تحقّق أن المفتاح الجديد يحمل الحِمل

أكّد أن الخلَف يخدم حركة المرور فعلاً قبل أن تلمس القديم. راقب صعود used_quota للمفتاح الجديد بينما يستوي للقديم — الاستخدام لكل مفتاح هو إشارة التحوّل لديك.
4

تقاعد المفتاح القديم

بمجرد ألا يُظهر المفتاح القديم حركة مرور، عطّله أولاً (قابل للعكس) وراقب المتأخّرين، ثم احذفه نهائياً. التعطيل هو الإيقاف المؤقت؛ والحذف نقطة اللاعودة.
اضبط وسم environment على كل مفتاح — أعد استخدامه عبر المفتاح القديم والجديد، أو ارفعه (prod ← prod-2026q2) — بحيث يُعنوَن الخلَف والسلَف بتمييز بينما كلاهما حيّ خلال نافذة التداخل.

​
3. تدوير ملموس، عبر REST

كل ما يلي إجراء في وحدة التحكم — تعمل مسارات الإدارة هذه تحت جلستك (UserAuth)، وليس مفتاح الترحيل. افترض أنك تستبدل مفتاح وكيل تلخيص مجدوَل. أنشئ الخلَف بنفس النطاق: 
# رمز جلسة وحدة التحكم — وليس مفتاح ترحيل sk-orca-…
curl https://api.orcarouter.ai/api/token \
  -H "Authorization: Bearer <your-session-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "summarizer-2026q2",
    "environment": "prod",
    "model_limits_enabled": true,
    "model_limits": "openai/gpt-4o-mini",
    "credit_limit_usd": 50,
    "expired_time": -1,
    "guardrail_id": 12,
    "firewall_policy_id": 7
  }'
تعيد الاستجابة النص الصريح مرة واحدة ("data": "sk-orca-…"). انسخه، وانشره إلى المُلخِّص، وأكّد أن المفتاح الجديد يخدم قبل المضي. عندما لا يُظهر المفتاح القديم (المعرّف 481) حركة مرور، عطّل ثم احذف: 
# أوقف مؤقتاً أولاً (قابل للعكس) — اضبط حالة المفتاح القديم على معطَّل (2)
curl -X PUT https://api.orcarouter.ai/api/token \
  -H "Authorization: Bearer <your-session-token>" \
  -H "Content-Type: application/json" \
  -d '{"id": 481, "status": 2}'

# بمجرد تأكدك أن لا شيء يعتمد عليه — ألغِ نهائياً
curl -X DELETE https://api.orcarouter.ai/api/token/481 \
  -H "Authorization: Bearer <your-session-token>"
حالة المفتاح إحدى Enabled (1)، Disabled (2)، Expired (3)، أو Exhausted (4). التعطيل يضبطها على Disabled؛ فيُرفض كل طلب يصدره المفتاح بينما تبقى إعداداته وروابطه وتاريخه سليمة. الحذف دائم — لا يمكن لبيانات الاعتماد أبداً أن تخوّل طلباً مجدداً، والمفتاح المحذوف غير قابل للاسترداد.
يمكنك فعل كل هذا دون API — شاشة المفاتيح بها مفتاح جديد، وزرّ معطَّل لكل مفتاح، وحذف (مفرد أو دُفعة). صيغة REST أعلاه للنصوص البرمجية لتدويرات مجدوَلة.

​
4. تدوير المفاتيح المربوطة بسياسة ومفاتيح البوابة

ربط حاجز الحماية وجدار الحماية لمفتاح يعيش على المفتاح، فيجب أن يحمل الخلَف نفس guardrail_id و firewall_policy_id لفرض نفس الموقف. شيئان يجب معرفتهما:
حواجز الحماية وسياسات جدار الحماية موارد مسمّاة ضمن نطاق مساحة العمل مشتركة عبر المفاتيح. تدوير مفتاح لا يلمس السياسة نفسها؛ أنت فقط تعيد توجيه مفتاح جديد إلى guardrail_id / firewall_policy_id الموجودين. تبقى السياسة تحكم حركة المرور دون انقطاع.
مفتاح مضبوط بـ is_firewall_gateway يقود مسارات بوابة جدار الحماية (/api/v1/firewall/*). سكّ واحد، وإعادة كشف نصه الصريح، يتطلبان كلاهما Admin. لأنك لا تستطيع إعادة قراءة سرّه باستهتار، التقط النص الصريح لمفتاح البوابة الجديد عند الإنشاء وخزّنه في مدير أسرارك قبل أن تتحوّل.
لا تعد استخدام مفتاح واحد — بوابة أو غيره — عبر وكلاء كثيرين و”تدوّر” بتعديل الحدود. مفتاح واحد لكل وكيل يُبقي كل تدوير معزولاً ونطاق الانفجار صغيراً. انظر قائمة تحقّق الاستقلالية الأدنى.

​
5. تدوير طارئ (تسرّب مشتبه به)

إذا ظننت أن مفتاحاً منكشف، ينقلب الترتيب: أوقف النزيف أولاً، ورحّل ثانياً.
  1. عطّل المفتاح المشبوه فوراً بحيث لا يستطيع تخويل أي شيء بينما تحقّق — أو احذفه صراحةً إن كان التسرّب مؤكداً.
  2. اسكّ الخلَف وأطلقه كما في §2.
  3. راجع ما فعله المفتاح المسرّب قبل أن تقطعه: صفِّ سجلات الطلبات حسب ذلك المفتاح (الرمز) لتحديد نطاق الانفجار.
دليل التشغيل الكامل للحادثة على الاستجابة للمفتاح المسرّب.
expired_time قصير هو تأمين تدوير: مفتاح منتهي الصلاحية يتقاعد نفسه حتى لو نسيت التدوير اليدوي، محدّداً كم يمكن لأي بيانات اعتماد واحدة أن يُساء استخدامها على الإطلاق.

​
6. الخطوات التالية

إدارة المفاتيح

دورة حياة الإنشاء / التعطيل / الإلغاء التي تبني عليها هذه الخطوات.

ربط السياسات بمفتاح

احمل نفس حاجز الحماية وسياسة جدار الحماية إلى الخلَف.

المفاتيح المنتهية الصلاحية

اضبط صلاحية بحيث تدوّر المفاتيح نفسها على مهلة.

الاستجابة للمفتاح المسرّب

المسار الطارئ حين تنكشف بيانات اعتماد.
التدوير مجرد تداخل منضبط: خلَف يعمل قبل أن يتوقف السلَف. أبقِ كل مفتاح محدّد النطاق بدقة ويبقى التسليم مملاً — وهو بالضبط ما تريده من تدوير بيانات اعتماد.