# אימות והיקפי הרשאה

## אסימוני גישה אישיים

צרו אסימונים ביישום 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` | שימוש ב-AI המנוהל של KolWrite (צ'אט, הטמעות, תמלול מהיר); צורך קרדיטים |
| `copilot:write` | הפעלת AI מדודה ושמירת השיחות ב-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`.

## קרדיטים וחיוב

בעת יצירת משימה מוקצים לה קרדיטים, וההתחשבנות מתבצעת בסיומה; קריאות AI נמדדות
לפי השימוש בטוקנים. בדקו את ההוצאות באמצעות `billing:read`:

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