# المصادقة والنطاقات

## رموز الوصول الشخصية

أنشئ رموز الوصول في تطبيق KolWrite (**الإعدادات → الحساب → الوصول إلى API**).
تبدو الرموز مثل `kol_...`، ولا تُعرض سوى مرة واحدة عند إنشائها، وتعمل
**بصلاحياتك**: يمكنها رؤية ملفاتك واستهلاك رصيدك وتلتزم بحدود خطتك.

أرسل رمز الوصول بإحدى الطريقتين الآتيتين — فهما متكافئتان:

```
Authorization: Bearer kol_...
X-API-Key: kol_...
```

- **انتهاء الصلاحية**: لا تنتهي صلاحية الرموز افتراضيًا؛ ويمكنك عند الإنشاء تحديد
  7 أو 30 أو 90 يومًا، أو تاريخ مخصص.
- **الإلغاء**: ألغِ أي رمز وصول في التطبيق (أو استخدم `DELETE
  /api/v1/api-keys/{id}` من جلسة مسجّل دخولها). يسري الإلغاء فورًا.
- لا يمكن لرموز الوصول مطلقًا إدارة الرموز أو حذف حسابك أو الوصول إلى
  نقاط النهاية الإدارية — بصرف النظر عن النطاقات.

## النطاقات

لا يمكن لرمز الوصول استدعاء سوى نقاط النهاية التي تغطيها النطاقات الممنوحة له. يتضمن كل
إجراء في [المرجع](/) تعليقًا يحدد النطاق المطلوب له
(`x-required-scope` في [مواصفات OpenAPI](/openapi.json)).

| النطاق | الصلاحيات الممنوحة |
|---|---|
| `files:read` | عرض الملفات والمجلدات والوسائط والمرفوعات وتنزيلها؛ وقراءة استخدام مساحة التخزين |
| `files:write` | رفع الملفات وتسجيل الوسائط وإنشاء المجلدات ومساحات العمل أو تحديثها |
| `jobs:read` | قراءة حالة المهمة وموضعها في قائمة الانتظار ونتائجها ونواتجها |
| `jobs:write` | إنشاء المهام وإلغاؤها (التحويل إلى نص ودمج التسميات التوضيحية)؛ وإعادة ترتيب قائمة الانتظار |
| `transcripts:read` | قراءة النصوص المفرّغة وإصداراتها وعناوين URL لتنزيل الصادرات |
| `transcripts:write` | حفظ إصدارات جديدة من النصوص المفرّغة واستعادة الإصدارات السابقة |
| `ai:use` | استخدام الذكاء الاصطناعي المُدار من KolWrite (الدردشة والتضمينات والتحويل السريع إلى نص)؛ ويستهلك الرصيد |
| `copilot:write` | تشغيل الذكاء الاصطناعي المُقاس وحفظ المحادثات في Copilot العام أو Copilot لنص مفرغ مصرح به |
| `shares:read` | عرض روابط المشاركة العامة وفحصها |
| `shares:write` | إنشاء روابط المشاركة العامة وتحديثها وتدويرها وإلغاؤها |
| `devices:read` | عرض جلسات الأجهزة المسجّل دخولها |
| `devices:write` | تسجيل خروج جلسات الأجهزة |
| `account:read` | قراءة إشارات الميزات وتفضيلات تجربة التطبيق |
| `account:write` | تحديث تفضيلات تجربة التطبيق |
| `billing:read` | قراءة رصيد الاعتمادات ودفتر العمليات والمنح |

الإعدادات المسبقة في التطبيق: **للقراءة فقط** (جميع نطاقات `*:read`)، و**الأتمتة**
(`files:*` و`jobs:*` و`transcripts:read` و`billing:read`)، و**الوصول الكامل**.

## أخطاء النطاقات

نطاق مفقود لنقطة نهاية مشمولة:

```json
{"detail": {"code": "insufficient_scope",
            "message": "This endpoint requires the 'jobs:write' scope",
            "required_scope": "jobs:write"}}
```

نقطة نهاية خارج النطاق المتاح لرموز الوصول العامة:

```json
{"detail": {"code": "pat_route_not_allowed",
            "message": "This endpoint is not available to personal access tokens"}}
```

تعيد كلتا الحالتين HTTP 403. أما رموز الوصول غير الصالحة أو الملغاة فتعيد HTTP 401 مع
`invalid_api_key`.

## الرصيد والفوترة

تحجز المهام الرصيد عند إنشائها وتسوّيه عند اكتمالها؛ وتُحتسب استدعاءات الذكاء الاصطناعي
وفق استخدام الرموز. تحقق من الإنفاق باستخدام `billing:read`:

- `GET /api/v1/billing/balance`
- `GET /api/v1/billing/ledger`