مفاتيح Admin API

أين تجد ذلك في لوحة المشرف: System › Settings › API & AI agents (/agent/keys)، علامة التبويب API keys. تحتوي نفس الصفحة على علامات التبويب Connect an AI و Connected apps و Activity.

الوظيفة

يسمح مفتاح Admin API (البادئة ak_) لعميل ذكاء اصطناعي أو برنامج نصي بإدارة لوحتك بالصلاحيات الدقيقة التي تمنحها إياه. وهو يعمل على Admin API ضمن /v1/admin/ وعلى نقطة نهاية Admin MCP ضمن /mcp/admin. وهو لا يعمل في أي مكان آخر.

ليس هو نفسه مفاتيح العملاء

ينشئ العملاء مفاتيح تبدأ بـ vk_ في بوابة العملاء (API keys and scopes). تصل هذه المفاتيح فقط إلى Customer API و /mcp. يتم رفض مفتاح ak_ على Customer API، ويتم رفض مفتاح vk_ على Admin API.

المتطلبات

العنصر	المتطلب
الدور	يجب عليك تسجيل الدخول بصفتك مشرفاً. لا يمكن للمفاتيح إنشاء مفاتيح أخرى.
عرض تجريبي	في لوحة تجريبية، تكون الصفحة للقراءة فقط: لا يمكن إنشاء أو إلغاء أي مفتاح.
إمكانية الوصول	يجب أن يتمكن العميل من الوصول إلى https://cloud.example.com/mcp/admin أو /v1/admin/... على لوحتك (تحقق من جدار الحماية الخاص بك إذا كنت تستخدم تقييد عناوين IP).

إنشاء مفتاح

1. افتح System › Settings › API & AI agents وابقَ في علامة التبويب API keys.

2. انقر فوق Create new key.

3. املأ النموذج:

   الحقل	القواعد
   الاسم	حتى 60 حرفاً، على سبيل المثال "Claude Code on my laptop".
   النطاقات	حدد واحداً على الأقل. راجع Scopes. ابدأ بـ admin:read فقط.
   تاريخ الانتهاء	1، 7، 30، 60 أو 90 يوماً. الافتراضي هو 30. الحد الأقصى 90. لا يمكن إنشاء مفتاح بدون تاريخ انتهاء.
   نطاقات عناوين IP (اختياري)	عنوان IPv4 أو IPv6 واحد أو CIDR في كل سطر، على سبيل المثال 203.0.113.0/24 أو 2001:db8::/48. بحد أقصى 32. اترك الحقل فارغاً للسماح بأي عنوان IP.
   المكالمات في الدقيقة	من 1 إلى 6000. الافتراضي هو 120.

4. انقر فوق Create key. يعرض المربع المفتاح مرة واحدة، على سبيل المثال ak_XXXX. انسخه الآن: لا تخزن NexCMP سوى تجزئة (hash) ولا يمكنها إظهاره مرة أخرى أبداً.

5. انقر فوق I have saved the key. افتح علامة التبويب Connect an AI للحصول على أوامر جاهزة للصق تحتوي مسبقاً على المفتاح الذي أنشأته للتو (فقط على هذه الصفحة، حتى تقوم بتحديثها).

النطاقات

لا يمكن لأي مفتاح استخدام سوى الأدوات ونقاط النهاية التي تسمح بها نطاقاتُه. لا تتضمن نطاقات الكتابة صلاحية القراءة: لذا يحتاج المفتاح الذي يجب أن يقرأ ويكتب إلى admin:read أيضاً.

النطاق	ما تسمح به
admin:read	قراءة الإعدادات، الكتالوج، العملاء، الفوترة والسجلات. لا يتم إرجاع الأسرار مطلقاً.
catalog:write	الخطط، قوالب نظام التشغيل، حصص الاستخدام، رموز الخصم.
infra:write	مصادر البنية التحتية (CloudStack، Proxmox)، المناطق، الخوادم.
billing:write	بوابات الدفع، العملة، الفواتير، الأرصدة. تتطلب العمليات المالية تأكيداً.
customers:write	العملاء والموزعون.
settings:write	الإعدادات العامة، العلامة التجارية، البريد الإلكتروني، الصفحات القانونية، الوحدات النمطية، الإشعارات.
ai:write	مزود الذكاء الاصطناعي وميزات الذكاء الاصطناعي.
secrets:write	كتابة كلمات المرور ومفاتيح API. يمكن تعيينها ولكن لا يمكن قراءتها مرة أخرى مطلقاً.

تعيين سر يتطلب نطاقين

أي طلب يحمل كلمة مرور أو مفتاح API أو قيمة رمز (كلمة مرور SMTP، مفتاح دفع، رمز بوت Telegram، مفتاح مزود الذكاء الاصطناعي، بيانات اعتماد CloudStack أو Proxmox) يحتاج إلى secrets:write بالإضافة إلى نطاق المنطقة (على سبيل المثال settings:write لـ SMTP). إذا كنت تفضل كتابة الأسرار بنفسك، فاترك secrets:write متوقفاً وأدخلها في لوحة الإدارة.

إلغاء مفتاح

1. ابحث عن المفتاح في الجدول (الحالة Active، Expired أو Revoked؛ يعرض Last used الوقت والعميل).
2. انقر على Revoke وأكد العملية.

يتوقف المفتاح عن العمل فوراً. عملية الإلغاء نهائية؛ أنشئ مفتاحاً جديداً إذا كنت بحاجة إليه مرة أخرى.

ما لا يفعله المفتاح أبداً

لا يمكن لمفتاح الوصول إلى هذه المناطق مطلقاً، بغض النظر عن نطاقاته. تتطلب هذه المناطق تسجيل دخولك كمدير.

• إنشاء أو تغيير مستخدمي الإدارة، المصادقة الثنائية (2FA) وأمان تسجيل الدخول، جلسات المشرف، ورموز API الخاصة بالإدارة.
• إنشاء أو سرد أو إلغاء مفاتيح المشرف، اتصالات OAuth وحسابات الذكاء الاصطناعي، أو استخدام وحدة تحكم الذكاء الاصطناعي.
• نسخ لوحة التحكم احتياطياً أو استعادتها، تحديثها، أو تغيير ترخيصها.
• تسجيل الدخول كعميل أو موزّع، فتح وحدة تحكم العميل، قراءة بيانات اعتماد الجهاز الافتراضي أو ملف kubeconfig، تعيين مفاتيح SSH، أو إرسال كلمات المرور أو إعادة تعيينها.
• تغيير وحدات الشبكة والتوجيه (BGP، FRR، RTBH، XDP، الواجهات، المسارات الثابتة ومسارات السياسة، NAT) أو الوكلاء الخارجيين وتكامل البوابة. هذه للقراءة فقط.
• تغيير الإعدادات مثل demo_*، admin_*، قوائم المضيفين، مفتاح المرور، إعادة المصادقة وأسرار اختبار التحقق (captcha).

أي شيء لا تغطيه قاعدة ما يكون مغلقاً افتراضياً للكتابة، وقابلاً للقراءة باستخدام admin:read للقراءة.

الإجراءات التي تتطلب تأكيدك

تنجح هذه الإجراءات فقط بعد موافقتك على معاينة (انظر Two-step confirmation):

• تغيير رصيد العميل أو محفظة الموزع، دفع الأموال، سجلات الفوترة، سعر الصرف.
• تغيير الأسعار (أسعار الخطط، إنشاء الخطط المجمعة، تسعير الصور والتخزين) وإنشاء رموز الخصم أو الأموال.
• حفظ بيانات اعتماد بوابة الدفع أو اتصال CloudStack.
• حذف أي شيء، حظر عميل أو حذفه، تغيير حدود العميل، تعليق موزّع أو إغلاقه.
• التفاعل مع خوادم العملاء، أو إنشاء خادم مدفوع لعميل.
• تغيير المفاتيح العامة للموقع، إعدادات أمان تسجيل الدخول أو إعدادات الدفع من خلال الإعدادات العامة.

التأكيد على خطوتين

عندما تحتاج عملية استدعاء إلى تأكيد، فلن يتغير شيء بعد. الرد هو HTTP 428 مع confirm_required، وconfirm_token، وpreview (الطريقة، المسار، السبب، القيم الجديدة، وعند توفرها، القيم الحالية) وexpires_in: 300.

1. يعرض لك العميل معاينة التغيير.
2. بعد الموافقة، يتم تكرار نفس الطلب (نفس الطريقة والمسار وbody) مع الترويسة X-Confirm-Token: <confirm_token>. تأخذ أدوات MCP الوسيط confirm_token بدلاً من ذلك.
3. الرمز يعمل لمرة واحدة وينتهي صلاحيته بعد 5 دقائق.

المفاتيح التي يتم إنشاؤها داخل لوحة المشرف لأجل AI Chat لا يمكن تأكيدها إلا على الشاشة: يقول الرد confirm_in: "ui" وتظهر بطاقة تأكيد في لوحة المشرف. لا يمكن للذكاء الاصطناعي الموافقة عليها.

قواعد الحد الأقصى للمعدل وعناوين IP

• عند تجاوز الحد المسموح به في الدقيقة، يُرجع الاستدعاء rate_limited (HTTP 429) مع Retry-After: 60.
• عند ضبط نطاقات IP، فإن الاستدعاءات الواردة من أي عنوان آخر تُرجع ip_not_allowed (HTTP 403).

سجل النشاطات

تُدرج تبويب Activity كل عملية استدعاء تتم باستخدام المفتاح، والأحدث أولاً: الوقت، المفتاح، العميل، طريقة الوصول (http، mcp، chat، cli، confirm، preview)، الطريقة والمسار، الأداة، حالة HTTP، عنوان IP والتفاصيل (المخفية). يمكنك البحث حسب المسار أو الأداة أو اسم المفتاح، أو إظهار الأخطاء فقط (HTTP 400 وما فوق) أو الاستدعاءات التي تنتظر التأكيد فقط (428 وما فوق)، وتحديد الفترة الزمنية لتشمل الساعة الأخيرة أو 24 ساعة أو 7 أيام. تحتفظ NexCMP بآخر 200,000 إدخال. تظهر التغييرات التي يتم إجراؤها عبر مفتاح أيضاً في Logs › Admin actions تحت اسم ak:<admin>/<key name>.

التحقق

اختبر مفتاح القراءة فقط من أي جهاز يقع داخل نطاق IP:

curl -s https://cloud.example.com/v1/admin/agent/tools \
  -H "Authorization: Bearer ak_XXXX"

ستحصل على قائمة بتنسيق JSON بالأدوات التي تسمح بها نطاقات صلاحياتك. قم بتشغيل إحداها:

curl -s -X POST https://cloud.example.com/v1/admin/agent/tools/system_health \
  -H "Authorization: Bearer ak_XXXX" \
  -H "Content-Type: application/json" -d '{}'

يتحدث وقت Last used الخاص بالمفتاح ويظهر الاستدعاء في Activity. يتم وصف قائمة الأدوات الكاملة ووصف OpenAPI (/v1/admin/openapi.json) في Connect an AI client.

الأخطاء

تأتي الأخطاء بتنسيق JSON: {"error": {"code": "...", "message": "..."}}.

HTTP	code	المعنى	الحل
401	invalid_key	المفتاح مفقود، أو غير مصاغ بشكل صحيح، أو غير معروف. يُعاد هذا الرد أيضاً عند استخدام مفتاح ak_ على مسار غير خاص بالمشرف.	تحقق من المفتاح؛ واستخدمه فقط على /v1/admin/ و/mcp/admin.
401	key_expired	انتهت صلاحية المفتاح.	أنشئ مفتاحاً جديداً.
401	key_revoked	تم إبطال المفتاح.	أنشئ مفتاحاً جديداً.
403	ip_not_allowed	عنوان IP الخاص بالمرسل خارج نطاقات IP المسموحة للمفتاح.	قم بالاستدعاء من عنوان IP مسموح به، أو أنشئ مفتاحاً بالنطاق الصحيح.
403	local_only_key	تم استخدام مفتاح مخصص لـ AI Chat أو لـ server CLI من جهاز آخر.	هذه المفتاح تعمل فقط على خادم لوحة التحكم نفسه.
403	insufficient_scope	المفتاح يفتقر إلى نطاق صلاحية (scope)؛ ويتضمن الرد required_scope.	أنشئ مفتاحاً يحتوي على هذا النطاق.
403	forbidden_for_keys	نقطة النهاية، أو الإعداد الذي حاولت تغييره، مغلقة أمام المفاتيح.	قم بذلك من خلال لوحة المشرف.
403	demo_read_only	لوحة التحكم في وضع التجربة (demo mode) والاستدعاء يحاول إجراء كتابة.	استخدم لوحة تحكم لا تعمل في وضع التجربة.
403	confirm_in_ui	يجب تأكيد هذا الإجراء على الشاشة في لوحة المشرف.	قم بالموافقة على بطاقة التأكيد.
428	confirm_required	المعايِنة جاهزة؛ لم يتغير شيء. تتضمن confirm_token.	اعرض المعاينة، ثم كرّر الطلب باستخدام X-Confirm-Token.
409	confirm_expired	الرمز أقدم من 5 دقائق.	أرسل الطلب مرة أخرى للحصول على معاينة جديدة.
409	confirm_mismatch	الرمز ينتمي إلى طلب مختلف (يختلف في الطريقة أو المسار أو body).	كرر الطلب المطابق تماماً.
409	confirm_invalid	رمز غير معروف أو تم استخدامه مسبقاً.	أرسل الطلب مرة أخرى للحصول على معاينة جديدة.
429	rate_limited	عدد كبير جداً من الاستدعاءات في هذه الدقيقة.	انتظر حتى Retry-After.
400	invalid_path	يحتوي المسار على تسلسلات محظورة.	استخدم مساراً بسيطاً.
413	too_large	النَتْل (الجسم) يتجاوز 10 ميغابايت.	أرسل بيانات أقل.
400	invalid_argument	معامل الأداة مفقود، أو غير معروف، أو ذو نوع خاطئ؛ وتسميه الرسالة.	أصلح المعامل.

الحدود والملاحظات

• اجعل المفاتيح قصيرة الأجل ومحدودة النطاق. يفضل مفتاح واحد لكل عميل لكي تتمكن من إبطال مفتاح واحد بشكل منفصل.
• المفتاح بقوة نطاقاته. secrets:write زائد billing:write هو التجميعة الأكثر حساسية؛ وتتوقف إجراءات الأموال عند المعاينة دائماً.
• المفاتيح المنشأة تلقائياً (لـ AI Chat و CLI الخادم) تعيش لدقائق معدودة وتعمل حصرياً من خادم اللوحة.
• لقطع اتصال عميل ذكاء اصطناعي فوراً، أبطل مفتاحه. يتم إبطال اتصالات OAuth من تبويب Connected apps (OAuth connectors).