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

# احصل على مفتاح API

> أنشئ المفاتيح ودوّرها واحذفها من صفحة التكاملات الخاصة بالوكيل.

تُدار المفاتيح في تطبيق Chattler، في صفحة **التكاملات** الخاصة بالوكيل، ضمن بطاقة **الوصول عبر API**. لا يوجد استدعاء API ينشئ مفتاحًا.

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

<Steps>
  <Step title="افتح الوكيل">
    في التطبيق، افتح الوكيل الذي تريد إتاحته وانتقل إلى صفحة **التكاملات** الخاصة به.
  </Step>

  <Step title="أضف مفتاحًا في بطاقة الوصول عبر API">
    أعطِ المفتاح اسمًا واختر صلاحيته:

    * `read-only`: عرض المحادثات وقراءة الرسائل.
    * `full`: كل ما سبق، بالإضافة إلى نقطتي نهاية الدردشة.
  </Step>

  <Step title="انسخ المفتاح الآن">
    يُعرض المفتاح الخام **مرة واحدة** فقط، مباشرة بعد الإنشاء. يبدو هكذا:

    ```text theme={null}
    cht_live_<key_id>.<secret>
    ```

    الجزء السري وحده هو ما يصادق. أما الجزء `key_id` فهو علني وهو معرّف المفتاح في كل مكان في لوحة التحكم. إذا فقدت السر، دوّر المفتاح.
  </Step>
</Steps>

## تدوير المفتاح

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

## حذف المفتاح

حذف المفتاح يزيله. من تلك اللحظة يفشل كل طلب به بالخطأ `401 invalid_api_key`، بلا فرق عن مفتاح لم يوجد قط. تبقى محادثاته وسجل طلباته قابلة للقراءة في لوحة التحكم. لا يمكن التراجع عن الحذف؛ أنشئ مفتاحًا جديدًا بدلًا منه.

<Warning>
  **لا تضع المفتاح أبدًا في حزمة متصفح أو تطبيق جوال أو أي عميل لا تتحكم فيه.** المفتاح بيانات اعتماد طويلة الأمد للمالك وينفق من رصيده. استدعِ API من الخادم الخلفي الخاص بك، ودوّر المفتاح فور الاشتباه بتسريبه.
</Warning>

## المصادقة بالمفتاح

لا تُقبل إلا ترويسة `Authorization` بنظام `Bearer`. تُتجاهل بيانات الاعتماد في سلسلة الاستعلام، ولا دخل لأي رمز من لوحة التحكم ولا لترويسة `Browser-ID`.

```http theme={null}
Authorization: Bearer cht_live_<key_id>.<secret>
```

المفتاح مرتبط بوكيل واحد. استخدامه مع `{agent_id}` مختلف يُرجع `403 agent_mismatch`.

## الإحصائيات

لا يُعرض الاستخدام في بطاقة الوصول عبر API. افتح صفحة **الإحصائيات** الخاصة بالوكيل واختر المفتاح في مرشّح **التكامل**؛ كل مفتاح مدرج هناك كتكامل مستقل. تعرض الصفحة بعدها، لكل مفتاح ولكل يوم بتوقيت UTC، عدد الطلبات، والطلبات الناجحة والفاشلة، ونسبة الأخطاء، ومتوسط زمن الاستجابة وزمن الاستجابة p95، والمستخدمين الفريدين، والمحادثات النشطة، والرموز، والمبلغ المحصّل، إضافة إلى تفصيل حسب نقطة النهاية وحالة HTTP ورمز الخطأ. لا تُكشف تكلفة المزوّد أبدًا؛ المبلغ المعروض هو ما حُصّل من الرصيد.