---
title: مفاتيح API والنطاقات
description: كيف يُنشئ العملاء مفاتيح API (بادئة vk_)، ويختارون النطاقات، ويقيدونها حسب عنوان IP وتاريخ انتهاء الصلاحية، وكيف يراجعها المشرفون ويلغونها.
url: https://nexcmp.com/ar/docs/developers/api-keys/
applies_to: NexCMP 1.6.1
updated: 2026-11-02
---

# مفاتيح API والنطاقات {#api-keys-and-scopes}

> **أين تجدها في البوابة:** مفاتيح API (`/api-keys`). **أين تجدها في لوحة المشرف:** Customers › Customers › API keys (`/customers/apikeys`).

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

يتيح **API key** لأي نص برمجي، أو مهمة تكامل مستمر (CI)، أو [`cmp` CLI](https://nexcmp.com/ar/docs/developers/cmp-cli/)، أو مساعد ذكاء اصطناعي ([MCP](https://nexcmp.com/ar/docs/developers/mcp/)) استدعاء [REST API](https://nexcmp.com/ar/docs/developers/api/) نيابةً عن عميل واحد، مع الصلاحيات (**النطاقات**) الممنوحة فقط. تبدأ مفاتيح العملاء بـ `vk_`. يمكنها قراءة الخدمات وإدارتها ولكن لا يمكنها **أبدًا** المساس بالمال أو الحساب نفسه.

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

| العنصر | المتطلب |
|---|---|
| العميل | جلسة بوابة مسجلة الدخول (لا يمكن لمفتاح إنشاء أو تعديل مفاتيح أخرى، ولا يمكن للمشرف انتحال صفة عميل فعل ذلك أيضاً). |
| المفتاح | مفاتيح API مُفعّلة افتراضياً. إذا تم إيقافها، ستستجيب الاستدعاءات برمز 401 `api_keys_disabled`. |
| الاعتمادات | لا تظهر نطاقات المنتج إلا عندما يكون هذا المنتج مُفعّلاً على الموقع. |

## إنشاء مفتاح (للعميل) {#create-a-key-customer}

1. سجّل الدخول إلى البوابة وافتح **API keys**.
2. انقر على **Create key**.
3. املأ النموذج:

   | الحقل | القاعدة |
   |---|---|
   | **Key name** | مطلوب، بحد أقصى 60 حرفاً ("deploy server"، "backup script"). |
   | **ما يمكن أن فعله هذا المفتاح** | حدد النطاقات التي تحتاجها — نطاق واحد على الأقل. يجب ألا يحصل مفتاح القراءة فقط على أي نطاق كتابة. توخ الحذر مع النطاقات التي تكلف مالاً أو تحذف بيانات. |
   | **Expiry** | أبداً، أو 30 يوماً، أو 90 يوماً، أو 1 سنة (يقبل API من 1 إلى 3650 يوماً). |
   | **السماح بالاتصالات من هذه عناوين IP فقط** | عنوان IP واحد أو نطاق CIDR في كل سطر، حتى 20 (IPv4 أو IPv6). الحقل الفارغ يعني أي عنوان IP. ثبت عنوان IP الخاص بخادومك كلما استطعت. |

4. أكد النموذج. يظهر المفتاح **مرة واحدة** في نافذة "تم إنشاء المفتاح — يتم إظهاره مرة واحدة". انسخه وانقر على **I saved the key**. يتم تخزين تجزئة SHA-256 فقط، لذا لا يمكن حتى للمشرف قراءته مرة أخرى؛ وإذا فقدته، فالغِ مفتاحك وأنشئ مفتاحاً جديداً.
5. تظهر البوابة أيضاً أمر `curl` جاهزاً لاختبار المفتاح.


يبدو المفتاح كـ `vk_` يليه سلسلة عشوائية طويلة. تظهر القائمة الأحرف الأولى فقط (على سبيل المثال `vk_a1b2c3d4`)، والنطاقات، وواريخ الانتهاء، وتاريخ اخر استخدام، وعدد الطلبات، والحالة (*Active*، *Expired*، *Revoked*).

### التعديل، الإلغاء، التدقيق {#edit-revoke-audit}

- **Edit** يغير الاسم، النطاقات، عناوين IP المسموح بها وتاريخ الانتهاء. لا يُسمح بذلك خلال الجلسة المنتحلة.
- **Revoke** يوقف المفتاح على الفور ولا يمكن التراجع عن ذلك. يُحتفظ بالصف لتبقى سجلات استخدامه متاحة.
- **Key usage log** يوضح أوامر الكتابة وكل خطأ خلال الـ 60 يوماً الماضية: الوقت، الطلب، المفتاح، النتيجة وعنوان IP المصدر.
- يمكن أن يحتوي الحساب على **10 مفاتيح نشطة** كحد أقصى افتراضياً.
- تظهر المفاتيح المُنشأة عبر سطر الأوامر CLI أو تسجيل دخول MCP تحت **Connected apps & devices** ويمكن إبطالها من هناك.

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

أسماء النطاقات لها الشكل `area:action`. النطاقات المعروضة تعتمد على المنتجات التي قمت بتفعيلها.

| النطاق | يسمح بـ |
|---|---|
| `catalog:read` | قراءة الخطط والكتالوج. |
| `vm:read` | قراءة الأجهزة الافتراضية، المقاييس وفواتير الأجهزة الافتراضية. |
| `vm:write` | إجراءات الطاقة، التغييرات البسيطة، جدار الحماية، اللقطات السريعة. |
| `vm:create` | **إنشاء الأجهزة الافتراضية (يكلف مالاً).** |
| `vm:plan` | **تغيير الخطة أو تغيير الحجم (يكلف مالاً).** |
| `vm:destroy` | **حذف الأجهزة الافتراضية.** |
| `vm:restore` | **استعادة جهاز افتراضي من لقطة (يكتب فوق القرص).** |
| `vm:console` | فتح تذاكر وحدة تحكم VNC. |
| `sshkey:read`, `sshkey:write` | قراءة، إضافة وإزالة مفاتيح SSH. |
| `volume:read`, `volume:write`, `volume:create`, `volume:destroy` | مجلدات البيانات (الإنشاء والتوسيع يكلفان مالاً؛ الحذف يفقد البيانات). |
| `backup:read`, `backup:write`, `backup:restore` | Backups (الاستعادة تكتب فوق القرص). |
| `billing:read` | المحفظة، الفواتير، سجل الدفع — **قراءة فقط**. |
| `bandwidth:buy` | **شراء ملحق نطاق التردد (يكلف مالاً).** |
| `account:read`, `account:write` | الملف الشخصي، النظرة العامة، النشاط، الإشعارات؛ `account:write` يحدد الإشعارات كمقروءة فقط. |
| `apikey:read` | سرد مفاتيح الحساب وسجل الاستخدام (لا يمكن الإنشاء، التعديل أو الإلغاء). |
| `apikey:self` | ضمني على كل مفتاح: فحص المفتاح المتصل (`GET /v1/apikeys/self`). |
| `ticket:read`, `ticket:write` | تذاكر الدعم. |
| `aff:read`, `transfer:read` | برنامج الشركاء التابعين وعمليات نقل الخدمة — قراءة فقط. |
| `k8s:read`, `k8s:write`, `k8s:create`, `k8s:scale`, `k8s:destroy`, `k8s:kubeconfig` | Kubernetes (الإنشاء والتوسيع يكلفان مالاً؛ ملف kubeconfig بصلاحية مسؤول المجموعة cluster-admin). |
| `vpc:read`, `vpc:write`, `vpc:create`, `vpc:destroy` | السحاب الخاص. |
| `image:read`, `image:write` | صور نظام التشغيل و ISO (يتم احتساب التخزين بالساعة). |
| `s3:read`, `s3:write`, `s3:create`, `s3:destroy`, `s3:keys` | Object Storage (يتم إظهار مفتاح الـ S3 السري مرة واحدة). |
| `vpn:read`, `vpn:detail`, `vpn:write`, `vpn:create`, `vpn:destroy` | شبكة VPN ووكيل IPv6 (تتضمن تفاصيل الاتصال كلمات سر الوكيل). |
| `dedicated:read`, `dedicated:write`, `dedicated:console`, `dedicated:create`, `dedicated:destroy` | الخوادم المخصصة (إنشاء الطلبات من المحفظة؛ الحذف يعيد تثبيت نظام التشغيل). |
| `shield:read`, `shield:write`, `shield:agent` | درع DDoS، فقط عند تفعيل تلك الوحدة. |

الطلب الذي يتجاوز نطاقات المفتاح يرد بـ **403 `scope_required`**؛ أما المسار الذي لا يحق لأي مفتاح طلبه فيرد بـ **403 `endpoint_not_public`**.

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

لا يمكن لأي نطاق فتح ما يلي: شحن الرصيد أو سحب الأموال، تغيير البطاقات أو الشحن التلقائي، تغيير كلمة المرور أو البريد الإلكتروني أو المصادقة الثنائية 2FA، حذف الحساب، أو إنشاء أو تعديل أو إلغاء مفاتيح أخرى. تتطلب هذه العمليات دائماً متصفحاً مسجلاً للدخول. حتى لو تسرب المفتاح، فلن يتمكن من الوصول إلى أموال العميل أو حسابه.

## قواعد يمكنك الاعتماد عليها {#rules-you-can-rely-on}

| القاعدة | التفاصيل |
|---|---|
| مرتبط بالموقع | يعمل المفتاح فقط على الموقع (النطاق) الذي تم إنشاؤه فيه. |
| حدود المعدل | لكل مفتاح ولكل حساب: 120 و300 طلب في الدقيقة افتراضياً. |
| منع التكرار | العمليات التي تكلف أموالاً أو لا يمكن تكرارها تتطلب ترويسة `Idempotency-Key`. |
| الحصص | يخضع المفتاح لنفس [حصص الاستخدام](https://nexcmp.com/ar/docs/billing/quotas/) الخاصة بالعميل. |
| حساب مقفل | تتوقف مفاتيح العميل المقفل عن العمل (403 `account_blocked`). |
| تدقيق | يتم تسجيل عمليات إلغاء المفاتيح من قبل المسؤول في سجل تدقيق المسؤول. |

## عرض المسؤول {#administrator-view}

1. افتح **Customers › API keys** (`/customers/apikeys`). يعرض الجدول اسم المفتاح والحروف الأولى منه، والمالك، والنطاقات، والحالة، وآخر استخدام (الوقت، عدد الطلبات، عنوان IP)، وتاريخ انتهاء الصلاحية.
2. قم بالتصفية حسب الموقع إذا كان لديك شركاء إعادة بيع. ابحث بالاسم أو المعرف أو بداية المفتاح.
3. انقر فوق **Revoke** لإيقاف مفتاح نشط، أو **Log** لعرض سجل استخدامه.
4. يمكن للمسؤولين **عرض وإلغاء** المفاتيح ولكن لا يمكنهم قراءتها أو إنشائها نيابة عن العملاء.

![قائمة المشرف لمفاتيح API الخاصة بالعملاء مع النطاقات، الحالة، الاستخدام الأخير وزر Revoke](https://nexcmp.com/ar/docs/images/developers/api-keys-02-admin.webp)

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

1. أنشئ مفتاحاً بالنطاق `vm:read` فقط.
2. تُرجع `curl -s https://cloud.example.com/v1/vm -H "Authorization: Bearer vk_XXXX"` قائمة الأجهزة الافتراضية.
3. ترد `curl -s -X POST .../v1/vm/<id>/start -H "Authorization: Bearer vk_XXXX"` بالرمز 403 `scope_required`.
4. قم بإلغاء المفتاح؛ سيُرجع الطلب الأول الآن 401 `key_revoked`.

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

- لا يتم عرض المفتاح مرة أخرى أبداً. تعامل معه ككلمة مرور وخزنه في مدير كلمات سر أو في أسرار نظام التكامل المستمر CI.
- يفضل تخصيص مفتاح واحد لكل سكريبت، بأضيق نطاقات ممكنة، مع صلاحية قصيرة وقائمة سماح لعناوين IP؛ قم بتدوير المفاتيح عن طريق إنشاء مفتاح جديد وإلغاء القديم.
- تكون صلاحية مفاتيح تسجيل الدخول للأجهزة (CLI، MCP) 90 يوماً افتراضياً.
- الموارد المحذوفة أو المنقولة لا تأثر بإلغاء المفتاح.

## استكشاف الأخطاء وإصلاحها {#troubleshooting}

| العَرَض | السبب | الحل |
|---|---|---|
| خطأ `too_many_keys` (422) | تم الوصول إلى الحد الأقصى للمفاتيح النشطة (10 مفاتيح افتراضياً) | قم بإلغاء مفتاح قديم. |
| خطأ `invalid_argument`: لم يتم اختيار أي نطاق | لم يتم تحديد أي نطاق | حدد نطاقاً واحداً على الأقل. |
| خطأ `invalid_argument` في عناوين IP المسموحة | العنصر المدخل ليس عنوان IP أو نطاقاً صحيحاً، أو طول بادئة خاطئ، أو يتجاوز 20 عنصراً | عنوان IP واحد أو نطاق CIDR في كل سطر، على سبيل المثال `203.0.113.0/24`. |
| تم رفض الإنشاء أثناء وضع تقمص الشخصية (Impersonation) | `impersonate_forbidden` | اطلب من العميل إنشاء المفتاح. |
| 401 `key_expired` | انقضى تاريخ انتهاء الصلاحية | أنشئ مفتاحاً جديداً. |
| 401 `key_ip_denied` | عنوان IP الخاص بالمرسل غير موجود في قائمة السماح | أضف عنوان IP أو أفرغ القائمة. |
| 401 `api_keys_disabled` | الميزة معطلة | استشر المسؤول لديك (إعداد `api_keys_enabled`). |