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

# المصادقة

> مفاتيح API والنطاقات والترويستان اللتان يحتاجهما كل طلب.

كل طلب يحتاج **ترويستين**:

```bash theme={null}
curl https://social.linkiasoft.com/api/v1/connect/channels \
  -H "x-api-key: lk_live_..." \
  -H "X-Tenant-Id: 8f6a2b3c-4d5e-4a7b-9c1e-3f2b1a9c0d4e"
```

| الترويسة      | ما هي                                     |
| ------------- | ----------------------------------------- |
| `x-api-key`   | مفتاح API لديك. وهو ما يصادق عليك.        |
| `X-Tenant-Id` | معرّف مساحة عملك (UUID). مطلوب في كل طلب. |

<Note>
  `X-Tenant-Id` **لا** يحدد أي مساحة عمل تقرأ. فالوصول محصور دائمًا بمساحة العمل المالكة لمفتاح
  API — وإرسال معرّف مساحة عمل شخص آخر لا يمنحك بياناته. والترويستان مطلوبتان ببساطة لقبول الطلب.
</Note>

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

في لينكياسوفت: **الإعدادات ← مفاتيح API ← إنشاء**.

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

## النطاقات

المفاتيح محدودة النطاق. والمفتاح الذي يفتقر إلى نطاق نقطة نهاية يحصل على `403` مع رسالة تسمّي ما
ينقصه:

```json theme={null}
{
  "statusCode": 403,
  "message": "API key missing required scope(s): conversations:read",
  "error": "Forbidden"
}
```

| النطاق                | يمنح                                                   |
| --------------------- | ------------------------------------------------------ |
| `conversations:send`  | إرسال الرسائل والوسائط والقوالب                        |
| `conversations:read`  | عرض المحادثات وقراءة رسائلها                           |
| `conversations:write` | الإسناد والإغلاق وإعادة الفتح والتفاعل والتعديل والحذف |
| `templates:read`      | عرض القوالب المعتمدة وفحصها                            |
| `channels:read`       | عرض القنوات المربوطة                                   |

**امنح الحد الأدنى.** فالتكامل الذي يرسل إشعارات فقط يحتاج `conversations:send` — وربما
`templates:read` و`channels:read` — ولا شيء غير ذلك. والمفتاح المحدود هكذا لا يستطيع قراءة صندوق
واردك حتى لو تسرّب.

<Note>
  المفتاح المنشأ **بلا** نطاقات يملك وصولًا كاملًا إلى مساحة عملك، للتوافق مع المفاتيح الصادرة قبل
  وجود النطاقات. اضبط النطاقات صراحةً دائمًا على المفاتيح الجديدة.
</Note>

## الأخطاء

| الحالة | المعنى                                                             |
| ------ | ------------------------------------------------------------------ |
| `400`  | طلب غير صالح. وحقل `message` يوضح ما يجب إصلاحه.                   |
| `401`  | المفتاح مفقود أو غير صالح أو مُبطَل أو منتهٍ.                      |
| `403`  | المفتاح صالح لكنه يفتقر إلى النطاق — أو بلغت مساحة العمل حد الخطة. |
| `404`  | لا يوجد سجل بهذا المعرّف **في مساحة عملك**.                        |

<Note>
  السجل الذي يخص مساحة عمل أخرى يعيد `404` لا `403`. وهذا مقصود: فـ`403` كان سيؤكد وجود السجل، وهو
  تحديدًا ما يريد معرفته من يخمّن المعرّفات. تعامل مع `404` على أنها «ليس لك أو غير موجود» — فالـ
  API لن يميّز.
</Note>

## حماية المفاتيح

* لا تضع مفتاحًا أبدًا في شيفرة الواجهة الأمامية أو تطبيق جوال أو أي شيء يستطيع العميل رؤيته —
  فهو يحمل وصولًا لمساحة العمل كلها ضمن نطاقاته.
* استخدم مفتاحًا منفصلًا لكل تكامل، حتى لا يوقف إبطال أحدها البقية.
* أبطل المفتاح فورًا من **الإعدادات ← مفاتيح API** إن انكشف؛ فيتوقف عن العمل في الحال.