---
title: مفاتيح Admin API
description: أنشئ وألغِ مفاتيح إدارة ak_ لوكلاء AI والبرامج النصية: النطاقات الثمانية، الصلاحية، نطاقات IP، حد المعدل، ما لا تستطيع المفاتيح فعله أبداً، وكل رمز خطأ.
url: https://nexcmp.com/ar/docs/configure-with-ai/admin-api-keys/
applies_to: NexCMP 1.6.1
updated: 2026-11-02
---

# مفاتيح Admin API {#admin-api-keys}

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

## الوظيفة {#what-it-does}

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

::: info ليس هو نفسه مفاتيح العملاء
ينشئ العملاء مفاتيح تبدأ بـ `vk_` في بوابة العملاء ([API keys and scopes](https://nexcmp.com/ar/docs/developers/api-keys/)). تصل هذه المفاتيح فقط إلى Customer API و `/mcp`. يتم رفض مفتاح `ak_` على Customer API، ويتم رفض مفتاح `vk_` على Admin API.
:::

## المتطلبات {#requirements}

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

## إنشاء مفتاح {#create-a-key}

1. افتح **System › Settings › API & AI agents** وابقَ في علامة التبويب **API keys**.
2. انقر فوق **Create new key**.
3. املأ النموذج:

   | الحقل | القواعد |
   |---|---|
   | الاسم | حتى 60 حرفاً، على سبيل المثال "Claude Code on my laptop". |
   | النطاقات | حدد واحداً على الأقل. راجع [Scopes](#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** للحصول على أوامر جاهزة للصق تحتوي مسبقاً على المفتاح الذي أنشأته للتو (فقط على هذه الصفحة، حتى تقوم بتحديثها).

![نافذة المفتاح الجديد مع الاسم، خانات النطاق، تاريخ انتهاء الصلاحية ونطاق IP المعبأة](https://nexcmp.com/ar/docs/images/configure-with-ai/admin-api-keys-01-create.webp)

![نافذة تعرض المفتاح الجديد مرة واحدة مع زر نسخ وتحذير](https://nexcmp.com/ar/docs/images/configure-with-ai/admin-api-keys-02-shown-once.webp)

## النطاقات {#scopes}

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

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

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

## إلغاء مفتاح {#revoke-a-key}

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

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

## ما لا يفعله المفتاح أبداً {#what-a-key-can-never-do}

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

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

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

### الإجراءات التي تتطلب تأكيدك {#actions-that-need-your-confirmation}

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

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

## التأكيد على خطوتين {#two-step-confirmation}

عندما تحتاج عملية استدعاء إلى تأكيد، فلن يتغير شيء بعد. الرد هو 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-limit-and-ip-rules}

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

## سجل النشاطات {#activity-log}

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

![تبويب Activity يعرض الاستدعاءات مع الحالة، العميل، الأداة وعنوان IP](https://nexcmp.com/ar/docs/images/configure-with-ai/admin-api-keys-03-activity.webp)

## التحقق {#verify}

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

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

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

```bash
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](https://nexcmp.com/ar/docs/configure-with-ai/mcp-admin/).

## الأخطاء {#errors}

تأتي الأخطاء بتنسيق 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` | معامل الأداة مفقود، أو غير معروف، أو ذو نوع خاطئ؛ وتسميه الرسالة. | أصلح المعامل. |

## الحدود والملاحظات {#limits-notes}

- اجعل المفاتيح قصيرة الأجل ومحدودة النطاق. يفضل مفتاح واحد لكل عميل لكي تتمكن من إبطال مفتاح واحد بشكل منفصل.
- المفتاح بقوة نطاقاته. `secrets:write` زائد `billing:write` هو التجميعة الأكثر حساسية؛ وتتوقف إجراءات الأموال عند المعاينة دائماً.
- المفاتيح المنشأة تلقائياً (لـ AI Chat و CLI الخادم) تعيش لدقائق معدودة وتعمل حصرياً من خادم اللوحة.
- لقطع اتصال عميل ذكاء اصطناعي فوراً، أبطل مفتاحه. يتم إبطال اتصالات OAuth من تبويب **Connected apps** ([OAuth connectors](https://nexcmp.com/ar/docs/configure-with-ai/oauth-connectors/)).