الانتقال إلى المحتوى الرئيسي
بيانات الاعتماد طويلة العمر مسؤولية تنمو بهدوء: يخرج الوكيل من الخدمة، ينتهي العرض التوضيحي، يمضي المتعاقد في طريقه — لكن المفتاح يبقى يعمل حتى يتذكّر أحدهم إلغاءه. مفتاح api منتهي الصلاحية يقلب ذلك الافتراض. تضبط تاريخ انتهاء عند سكّ المفتاح، ويتوقف OrcaRouter عن تخويله لحظة مرور ذلك التاريخ — لا مهمة تنظيف تنساها، ولا نافذة “مسرّب-لكن-لا-يزال-حياً”. الصلاحية حقل واحد على كائن الرمز: expired_time. هذه الصفحة هي الدليل المركّز لذلك التحكّم الواحد. لجانب سقف الإنفاق من نفس الشاشة، انظر سقف الحصة والصلاحية.

​
1. لماذا تضبط مفتاح api منتهي الصلاحية

الهدف من مفتاح محدّد بزمن هو جعل النتيجة الآمنة هي الافتراضية. بضع حالات تؤتي فيها أُكلها:

الوكلاء الزائلون

مهمة مجدوَلة أو وكيل قصير العمر يحصل على مفتاح يموت مع دورة حياة النشر. مهمة cron منسية لا يمكنها أن تبقى تنفق بعد شهور.

العروض والتجارب

سلّم عميلاً محتملاً مفتاحاً يعمل طوال مدة التقييم ثم يخمد من تلقاء نفسه — دون حاجة إلى إلغاء لاحق.

المتعاقدون والموردون

حدّد نطاق بيانات اعتماد على نافذة التعاقد. حين ينتهي العقد، ينتهي المفتاح.

وصول محدّد النطاق بالحادثة

امنح مفتاحاً ضيّقاً وقصير العمر أثناء حادثة بحيث لا يستطيع الوصول المرتفع أن يتجاوز عمر الحادثة نفسها.
تقترن الصلاحية طبيعياً ببقية مفتاح الاستقلالية الأدنى — قائمة سماح نماذج، وقائمة سماح IP، وسقف إنفاق. كلٌّ يحدّ محوراً مختلفاً؛ ومعاً يُبقون نطاق انفجار مفتاح مخترَق صغيراً. انظر قائمة تحقّق الاستقلالية الأدنى.

​
2. حقل expired_time

تعيش صلاحية المفتاح في حقل واحد على كائن الرمز:
الحقلالنوعالمعنى
expired_timeطابع زمني Unix (ثوانٍ)اللحظة المطلقة التي يتوقف فيها المفتاح عن التخويل. -1 يعني لا تنتهي الصلاحية أبداً.
شيئان يجب تذكّرهما:
  • expired_time مطلق، وليس مدة. تضبط اللحظة التي يموت فيها المفتاح، لا “بعد 30 يوماً من الآن” — منتقي التاريخ في وحدة التحكم يحسب الطابع الزمني لك.
  • الافتراضي لمفتاح جديد هو -1 (أبداً). لا ينتهي مفتاح إلا إذا أعطيته طابعاً زمنياً حقيقياً؛ ترك الحقل دون مساس يسكّ مفتاحاً لا ينتهي.
مفتاح لا ينتهي (expired_time = -1) هو الخيار الصحيح فقط لبيانات اعتماد تدوّرها بنشاط. إذا استطعت تسمية التاريخ الذي ينبغي أن يتوقف فيه مفتاح عن العمل — وللوكلاء والعروض والمتعاقدين تستطيع عادةً — فاضبطه. مفتاح -1 غير مراقَب هو الأرجح أن يتجاوز غرضه.

​
3. اضبط صلاحية في وحدة التحكم

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

​
4. ماذا يفعل مفتاح منتهي الصلاحية

عندما يُقدَّم مفتاح بعد مرور expired_time الخاص به، ترفضه البوابة في طبقة المصادقة — لا يصل الطلب أبداً إلى نموذج، فلا يكلّف أي حصة. تنتقل حالة المفتاح إلى Expired، إحدى الحالات النهائية التلقائية التي يمكن أن يبلغها مفتاح:
الحالةكيف تُبلَغ
Enabledنشط؛ الطلبات مخوَّلة.
Disabledأوقفته أنت؛ قابل للعكس.
Expiredتجاوز expired_time — يُبلَغ تلقائياً.
Exhaustedتخطّى حصته / سقف إنفاقه — يُبلَغ تلقائياً.
Expired نهائي بمعنى أن المفتاح لن يخوّل مجدداً من تلقاء نفسه. إن احتجته عائداً، عدّل المفتاح لدفع expired_time إلى المستقبل (Developer+) ويعود إلى Enabled في الطلب التالي — المفتاح وحدوده وروابط سياساته كلها محفوظة. لتقاعد مفتاح نهائياً بدلاً من ذلك، ألغِه.
الصلاحية مقابل التعطيل مقابل الإلغاء. الصلاحية هي مفتاح الإطفاء المجدوَل — تقرر المهلة سلفاً وتمضي. التعطيل هو الإيقاف المؤقت اليدوي القابل للعكس لحادثة. الإلغاء (الحذف) دائم. اعتمد على الصلاحية كلما عرفت سلفاً متى ينبغي أن تتوقف بيانات اعتماد عن الأهمية.

​
5. مثال معالَج: مفتاح عرض توضيحي مدته أسبوعان

افترض أنك تمنح عميلاً محتملاً مفتاحاً لتقييم مدته 14 يوماً. تريده أن يستدعي نموذجاً رخيصاً واحداً، وألا ينفق أكثر من ميزانية ثابتة، وأن يخمد عند انتهاء التجربة — كل ذلك دون تذكير في التقويم لإلغائه. في مربع حوار مفتاح جديد، اضبط:
  • model_limits: ["openai/gpt-4o-mini"] — لا يستطيع العرض الوصول إلى نموذج أغلى.
  • credit_limit_usd: ميزانية تجربة ثابتة — حلقة انفلات لا يمكنها تجاوزها.
  • expired_time: نهاية نافذة الـ 14 يوماً — يتوقف المفتاح عن التخويل من تلقاء نفسه عند انتهاء التجربة.
بعد المهلة، يُرفض أي طلب إضافي على هذا المفتاح دون إنفاق حصة، ويُظهر المفتاح Expired في القائمة. لا شيء عليك تنظيفه؛ تقاعدت بيانات الاعتماد نفسها. 
# قبل الانتهاء — مخوَّل
curl https://api.orcarouter.ai/v1/chat/completions \
  -H "Authorization: Bearer sk-orca-..." \
  -H "Content-Type: application/json" \
  -d '{"model": "openai/gpt-4o-mini", "messages": [{"role":"user","content":"ping"}]}'

# بعد الانتهاء — يُرفض الاستدعاء نفسه في طبقة المصادقة،
# لا يُستدعى النموذج أبداً، ولا تُستهلَك أي حصة.

​
6. مَن يستطيع فعل ماذا

الصلاحية محكومة بنفس بوابة الدور التي تحكم بقية دورة حياة المفتاح، ضمن نطاق مساحة عملك النشطة:
الإجراءالدور الأدنى
عرض صلاحية مفتاحViewer
ضبط أو تغيير expired_time (إنشاء / تعديل مفتاح)Developer
إعادة كشف النص الصريح لمفتاح عاديDeveloper
قراءة النص الصريح لمفتاح ضمن نطاق البوابة (is_firewall_gateway)Admin
لدورة الحياة الكاملة — إنشاء، تعطيل، إلغاء — ونمط التدوير الذي يقترن بالصلاحية، انظر إدارة المفاتيح.

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

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

شقيق سقف الإنفاق للصلاحية — احدّ مفتاحاً بالدولار كما بالوقت.

تدوير المفاتيح

التسليم بلا توقف الذي يمنع مفتاحاً لا ينتهي من العيش إلى الأبد.

كائن الرمز

كل حقل يحمله مفتاح، بما في ذلك expired_time، وما يقيّده كلٌّ منها.

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

اجمع الصلاحية مع حدود النماذج وقوائم سماح IP وسقوف الإنفاق لمفتاح بأدنى نطاق انفجار.
مفتاح يعرف متى يتوقف هو بيانات اعتماد أقلّ عليك تذكّر تقاعدها. اضبط expired_time كلما استطعت تسمية التاريخ — ودع البوابة تقوم بالتنظيف عنك.