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

تدير صفحة API Keys في /api-keys بيانات اعتماد واجهة REST ضمن /api/v1/. يتطلب إنشاء المفاتيح واستخدام الواجهة خطة Enterprise أو Manufacturer بحالة اشتراك active أو trialing. لا تتضمن خطتا Free وProfessional وصول REST.

سجّل الدخول لإدارة مفاتيح حسابك. تظل إمكانية عرض المفاتيح الموجودة وإلغائها وحذفها متاحة بعد تخفيض الخطة أو إلغاء الاشتراك؛ ولا تعيد صلاحية الأمان هذه حق إنشاء مفاتيح أو استخدام REST. ظهور المفتاح بحالة Active لا يثبت أن اشتراك مالكه مؤهل حاليًا.

لا توجد في هذه الصفحة خيارات لاختيار الصلاحيات أو تاريخ الانتهاء، أو لتغيير الاسم أو تحرير حد الطلبات. يرسل النموذج الحالي calc:read وprojects:read ولا يحدد انتهاءً. لا تستنتج نقاط نهاية من أسماء الصلاحيات: يوفّر موجّه REST الحالي مسارات الحساب والمبرّدات وhealth، وليس قراءة المشاريع. لا تعرض الصفحة خيار صلاحية شاملة بعلامة بدل.

الحد هو عشرة سجلات مفاتيح محفوظة لكل حساب، بما فيها الملغاة، وليس عشرة مفاتيح نشطة. الإلغاء يبقي السجل ولا يحرر مكانًا؛ حذف سجل ملغى من الصفحة يحرر مكانًا. يُعطّل New Key عند وجود عشرة سجلات، وأثناء التحميل، وعند خطأ القائمة، أو دون خطة مؤهلة.

1. افتح API Keys بعد تسجيل الدخول. انتظر اكتمال تحميل القائمة، وعالج أي خطأ تحميل قبل إنشاء مفتاح.
2. اختر New Key أو Create Key في القائمة الفارغة. أدخل في Key Name اسمًا يحدد التطبيق أو البيئة، دون أسرار أو بيانات عملاء.
3. اضغط Create مرة واحدة وانتظر النتيجة. تُزال المسافات من طرفي الاسم ويجب ألا يكون فارغًا؛ يقبل الخادم حتى 255 محرفًا. يغلق Cancel الحوار دون إنشاء مفتاح.
4. بعد النجاح، انسخ المفتاح الكامل من لوحة Save your API key now واحفظه بأمان قبل إغلاق اللوحة أو مغادرة الصفحة أو إعادة تحميلها.

تبدأ مفاتيح REST بالبادئة exk_ وتتبعها 64 خانة سداسية عشرية. يخزن الخادم تجزئة SHA-256 وبادئة تعريف من 12 محرفًا، وليس نسخة قابلة للاسترجاع من بيانات الاعتماد الكاملة. لا يُعاد المفتاح الكامل إلا في استجابة الإنشاء، ولا يمكن كشفه لاحقًا من القائمة.

استخدم زر النسخ ثم تحقق من وصول المفتاح الكامل إلى مخزن الأسرار المعتمد. إذا منع المتصفح الحافظة، فانسخ مباشرة من اللوحة ما دامت ظاهرة. إشعار النسخ وحده لا يثبت حفظ السر بصورة صحيحة. إغلاق اللوحة يمسح قيمتها المعروضة، وإعادة التحميل أو المغادرة يفقدان فرصة الحفظ هذه.

• احفظ السر في مدير أسرار على الخادم أو إعداد بيئة محمي، ولا تضعه في كود المتصفح أو مستودع عام أو لقطة شاشة أو عنوان URL أو مطالبة أو ملف حساب مشترك.
• استخدم، متى أمكن وضمن حد السجلات، مفاتيح مسماة منفصلة للتكاملات المختلفة كي تعالج الحوادث دون استبدال بيانات اعتماد غير متأثرة.
• إذا فُقد المفتاح فلا توجد عملية لكشفه أو استرجاعه. حدد سجله القديم وألغِه، ثم أنشئ بديلًا واضبطه إذا كانت الخطة مؤهلة.

تحتوي استجابة الإدارة فقط على بيانات وصفية محددة، وتستبعد التجزئة والمفتاح الكامل ومعرّف المالك. لا يعرض الجدول عدد الطلبات أو الصلاحيات أو الانتهاء أو حد كل مفتاح الموجودة في البيانات الوصفية. لا يوجد هنا سجل طلبات كامل أو عرض قابل لتحرير تفاصيل المفتاح.

تحديث آخر استخدام غير متزامن، ويحدث بعد المصادقة وتحديد المعدل وقبل فحص صلاحية نقطة النهاية واكتمال الحساب. قد يتأخر ولا يثبت نجاح الحساب.

أرسل في التكامل المفتاح الكامل لـ REST داخل ترويسة Authorization كبيانات اعتماد Bearer عبر HTTPS. لن تعمل البادئة أو رمز MCP بدلًا منه. النص التالي قالب ترويسة فقط، وليس طلبًا للتنفيذ. راجع مرجع نقطة النهاية لعقد المدخلات والوحدات الفعلي؛ مثال الحساب المختصر في صفحة المفاتيح ليس مواصفة كاملة للمدخلات.

حد REST الافتراضي هو 100 طلب في الدقيقة لكل مفتاح. تتضمن الاستجابات التي تبلغ محدد المعدل X-RateLimit-Limit وX-RateLimit-Remaining وX-RateLimit-Reset؛ وتمثل Reset طابع Unix الزمني بالثواني. المحدد الحالي في ذاكرة عملية الخادم، وليس حصة مشتركة مضمونة بين النسخ. القيمة المعروضة ليست ضمانًا لمعدل المعالجة.

• 401: تحقق من ترويسة Bearer المفقودة أو غير الصحيحة، أو نوع اعتماد خاطئ، أو مفتاح مبتور أو غير معروف. لا تُدرج المفتاح في تقرير خطأ.
• 403: اقرأ الرسالة لتمييز الإلغاء أو الانتهاء أو الاشتراك غير المؤهل أو نقص صلاحية نقطة النهاية. إنشاء مفتاح آخر لا يعالج قيود الاشتراك.
• 429: أوقف المحاولات السريعة وانتظر إعادة ضبط النافذة. أخطاء المدخلات والمحلّل منفصلة عن إدارة المفاتيح؛ احتفظ بالخطأ المُعاد بدل اعتباره نتيجة صحيحة.

Authorization: Bearer <EXCOIL_REST_API_KEY>

• نظرة عامة على REST API
• مرجع نقاط نهاية الحساب

تعرض الصفحة Delete للصفوف الملغاة فقط. تُفحص ملكية السجلات في عمليات الإدارة، بما فيها بعد تخفيض الخطة. لا تخلط إلغاء REST بإلغاء اتصال MCP مستقل.

1. حدد السجل الصحيح بالاسم والبادئة. خطط لاستبدال التكامل المستخدم أولًا، إلا إذا استدعى الاشتباه بتسريب إلغاءً فوريًا.
2. اختر Revoke في الصف النشط. اقرأ التأكيد وتحقق من الاسم؛ لا يغير Cancel شيئًا. أكد Revoke key عندما تكون مستعدًا لمنع الطلبات الجديدة باستخدامه.
3. انتظر الاكتمال وتحديث القائمة. يجب أن يصبح الصف Revoked، وينخفض العدد النشط، ويحل Delete محل Revoke. لا يمكن إعادة تنشيط مفتاح ملغى.
4. لإزالة السجل المتبقي وتحرير مكان، اختر Delete في الصف الملغى، وتحقق من الاسم ثم أكد Delete key. إزالة السجل دائمة ولا يمكن التراجع عنها.

تظهر رسالة انتظار أثناء تحميل القائمة. عند الفشل يظهر الخطأ وزر Try again؛ لا تعتبر فشل التحميل حسابًا فارغًا. تعرض القائمة الفارغة الناجحة No API keys yet. تعرض أخطاء الإنشاء والإدارة رسائل الخادم؛ وتبقى أخطاء الإلغاء والحذف أيضًا داخل حوار التأكيد.

تُعطّل عناصر التأكيد أثناء الإلغاء أو الحذف لتجنب الإرسال المكرر. إذا فشل الطلب أو كانت نتيجته غير مؤكدة، فاحتفظ بالرسالة دون أسرار، وأعد تحميل القائمة وافحص الصف المحدد قبل المحاولة مجددًا. إعادة فتح الصفحة أو تحميلها تحدث الحالة لكنها لا تسترجع المفتاح الكامل الذي أُنشئ للتو.

• بعد إنشاء غير مؤكد النتيجة، ابحث عن السجل بالاسم قبل إنشاء نسخ مكررة. إن وُجد ولم تحفظ السر، فألغِه واستبدله؛ لا يمكن الاسترجاع من البيانات الوصفية.
• إذا ظل New Key غير متاح، فتحقق من أهلية الاشتراك وأخطاء التحميل وإجمالي السجلات. الإلغاء وحده لا يقلل الإجمالي.
• بعد النجاح، تحقق من الحالة المتوقعة: Revoked بعد الإلغاء، واختفاء الصف بعد الحذف. إذا بقي التعارض بعد التحميل، فلا تفترض النجاح ولا تكشف الأسرار عند طلب المساعدة.

تُدار MCP في صفحة /mcp المنفصلة وتستخدم رموز Bearer مخصصة تبدأ بـ exm_ للوصول إلى /api/mcp. لا تصلح مفاتيح REST التي تبدأ بـ exk_ لاعتماد MCP، ولا تحل رموز MCP محل مفاتيح REST. يتطلب إنشاء MCP واستخدامه Manufacturer بحالة active أو trialing؛ ولا تكفي Enterprise وحدها.

تستخدم MCP إعداد Bearer يدويًا وليس OAuth. لرموزها نطاقات مستقلة وخيارات صلاحية 7/30/90 يومًا ومسار إلغاء مستقل؛ وقراءة المشاريع اختيارية بإذن منفصل. لا يقدم نموذج REST هذه الضوابط. يظل عرض اتصالات MCP القديمة وإلغاؤها متاحًا بعد تخفيض الخطة.

استخدم عميلًا متوافقًا ونقطة النهاية المعروضة في صفحة MCP المنشورة؛ توفر الخدمة لا يضمن دعم كل عميل ذكاء اصطناعي. إنشاء مفتاح REST أو اتصال MCP لا يمنح ملفات تصنيع أو عمليات فوترة أو وصولًا إداريًا. تظل تفاصيل التصنيع حصرية لخطة Manufacturer ضمن مسارات المنتج الفعلية.

• فهرس الوثائق