> ## Documentation Index
> Fetch the complete documentation index at: https://developers.huechat.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# مفاتيح API المحدودة النطاق

> أقل الصلاحيات، حدود لكل مفتاح، وتدوير بلا توقف.

المفتاح المحدود هو ما تمنحه لأي تكامل. بخلاف الرمز الشخصي يمكن حصره في بضعة
نطاقات، وتقييد معدله وحده، وتثبيته على عناوين IP خوادمك، وضبط انتهاء
صلاحيته.

<Note>
  مديرو الحساب وحدهم يستطيعون إنشاء المفاتيح أو تعديلها أو إلغاءها.
</Note>

## إنشاء مفتاح

```bash theme={null}
curl -X POST https://app.huechat.ai/api/v2/accounts/$ACCOUNT_ID/api-keys \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "مزامنة CRM",
    "description": "وصول للقراءة فقط لمزامنة جهات الاتصال والمحادثات",
    "scopes": ["contacts:read", "conversations:read", "messages:read"],
    "rate_limit_rpm": 500,
    "allowed_ips": ["203.0.113.0/24"],
    "expires_at": "2027-01-01T00:00:00Z"
  }'
```

تحمل الاستجابة قيمة `token` الكاملة **مرة واحدة**. احفظها فورًا؛ القراءات
اللاحقة تعيد `token_prefix` فقط.

## النطاقات

| النطاق                                   | يسمح بـ                                               |
| ---------------------------------------- | ----------------------------------------------------- |
| `conversations:read`                     | عرض المحادثات والبحث والتصفية                         |
| `conversations:write`                    | الإنشاء والتحديث والتعيين وتغيير الحالة والكتم        |
| `conversations:delete`                   | حذف المحادثات                                         |
| `contacts:read`                          | عرض جهات الاتصال والبحث فيها                          |
| `contacts:write`                         | إنشاء جهات الاتصال وتحديثها واستيرادها ودمجها         |
| `contacts:delete`                        | حذف جهات الاتصال                                      |
| `messages:read`                          | عرض رسائل المحادثة                                    |
| `messages:write`                         | إرسال الرسائل وإعادة المحاولة والترجمة                |
| `inboxes:read`                           | عرض صناديق الوارد                                     |
| `inboxes:write`                          | إنشاء صناديق الوارد وتحديثها وحذفها                   |
| `teams:read`                             | عرض الفرق والأعضاء                                    |
| `teams:write`                            | إنشاء الفرق وتحديثها وحذفها                           |
| `agents:read`                            | عرض الوكلاء وتوفرهم                                   |
| `ai_agents:read`                         | عرض وكلاء الذكاء الاصطناعي ومصادر المعرفة والإحصاءات  |
| `ai_agents:write`                        | إنشاء وكلاء الذكاء الاصطناعي وتحديثهم ونشرهم وتدريبهم |
| `broadcasts:read`                        | عرض الحملات والتقارير                                 |
| `broadcasts:write`                       | إنشاء الحملات وإرسالها وإلغاؤها                       |
| `webhooks:read`                          | عرض اشتراكات Webhooks                                 |
| `webhooks:write`                         | إنشاء اشتراكات Webhooks وتحديثها وحذفها               |
| `reports:read`                           | التقارير والتحليلات                                   |
| `labels:read` / `labels:write`           | التصنيفات                                             |
| `automations:read` / `automations:write` | قواعد الأتمتة والماكروهات                             |
| `account:read`                           | إعدادات الحساب                                        |

تعرض أداة الاختيار في **الإعدادات ← المطوّرون ← مفاتيح API** كل النطاقات التي
يمكن للحساب منحها، بما فيها الأحدث للقوالب وسير العمل والتذاكر والصفقات
والمواعيد.

## إدارة المفاتيح

| الإجراء                                  | الاستدعاء                                                     |
| ---------------------------------------- | ------------------------------------------------------------- |
| العرض                                    | `GET /api/v2/accounts/{account_id}/api-keys`                  |
| تعديل النطاقات أو الحد أو IP أو الانتهاء | `PATCH /api/v2/accounts/{account_id}/api-keys/{key_id}`       |
| التدوير                                  | `POST /api/v2/accounts/{account_id}/api-keys/{key_id}/rotate` |
| الإلغاء                                  | `DELETE /api/v2/accounts/{account_id}/api-keys/{key_id}`      |
| سجل الاستخدام                            | `GET /api/v2/accounts/{account_id}/api-keys/{key_id}/usage`   |

يعيد التدوير قيمة `token` جديدة لمعرّف المفتاح نفسه، فتبدّل السر في تكاملك
دون المساس بالنطاقات أو الحدود.

## الحدود لكل مفتاح

يقبل `rate_limit_rpm` من 1 إلى 100,000 طلب في الدقيقة، والافتراضي 1,000.
تعرض [ترويسات حد المعدل](/ar/rate-limits) في كل استجابة موقف المفتاح.

<Tip>
  مفتاح واحد لكل تكامل. عند إيقاف شريك أو خدمة، يزيل إلغاء مفتاحه ذلك الوصول
  تحديدًا ولا شيء غيره.
</Tip>