# API Keys API

נקודות קצה אלו מאפשרות לך לנהל את מפתחות ה-API של החשבון שלך מתוך קוד. כולן פועלות אך ורק על המפתחות של החשבון שמבצע את הקריאה.

קיימים שני סוגים של מפתחות, והם נמצאים בנתיבים נפרדים:

- **המפתח הראשי שלך** — מפתח הגישה המלא היחיד תחת **הגדרות ← אינטגרציות ← מפתח API**. ניתן לצפות בתצוגה המקדימה המוסתרת שלו, לבדוק את ניצול מכסת הקריאות שלך, לרענן אותו או לבטל אותו. אלו הן נקודות הקצה `/api-keys/current`, `/api-keys/rotate` ו-`/api-keys/usage` להלן.
- **מפתחות מוגבלי היקף (Scoped keys)** — מפתחות נוספים בעלי שם שאתה יוצר עבור משימה ספציפית, כאשר כל אחד מהם מוגבל לחלקים ב-API שתבחר. אלו הן נקודות הקצה `/api-keys` ו-`/api-keys/{id}` תחת [מפתחות מוגבלי היקף](#scoped-keys). שום דבר במפתח הראשי שלך לא משתנה כשאתה יוצר מפתח כזה; אינטגרציות קיימות ממשיכות לפעול ללא שינוי.

כל הנתיבים להלן יחסיים לכתובת ה-URL הבסיסית של ה-API:

```
https://api.youraiconnector.com/v1
```

כל בקשה חייבת לעבור אימות. ראה [Authentication](authentication.md) עבור ארבע השיטות המקובלות. הדוגמאות כאן משתמשות ב-header מסוג `X-API-Key` (וטופס פרמטר שאילתה אחד עבור cURL).

> **קרא זאת תחילה.** החלפה או ביטול של המפתח שלך נכנסים לתוקף **באופן מיידי**. ברגע שאחת מהקריאות מצליחה, המפתח הישן מפסיק לעבוד — כל אינטגרציה שעדיין משתמשת בו תתחיל לקבל שגיאות `401`. תכנן זאת מראש: בצע החלפה במהלך חלון תחזוקה ועדכן את כל האינטגרציות שלך מיד.

---

## קבלת מטא-נתונים של המפתח הנוכחי

מחזיר את המפתח הפעיל שלך: המפתח המלא ב-`api_key` כאשר קיימת עותק שניתן לאחזור, תצוגה מקדימה מוסתרת (4 התווים הראשונים ו-4 האחרונים), וכאשר זמין, התאריך שבו הוא נוצר. `api_key` הוא `null` עבור מפתחות שנוצרו לפני שנשמרו עותקים שניתן לאחזור — בצע סיבוב (rotate) פעם אחת והמפתח החדש יוצג שוב במועד מאוחר יותר.

`GET /api-keys/current`

**cURL**

```bash
curl "https://api.youraiconnector.com/v1/api-keys/current?apiKey=YOUR_API_KEY"
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/api-keys/current", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
```

**Python**

```python
import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/api-keys/current",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
```

**תגובה**

```json
{
  "success": true,
  "api_key": "abcdEFGH1234ijkl5678MNOP9012qrst",
  "api_key_masked": "abcd...qrst",
  "created_at": "2026-06-01T10:00:00.000Z"
}
```

אם לחשבון אין מפתח API, התגובה היא `404` עם `{ "success": false, "error": "No API key found for this account" }`.

---

## קבלת ניצול מגבלת הקצב

מחזיר את ניצול מגבלת הקצב שלך עבור החלון הנוכחי: מגבלת הבקשות לכל חלון, כמה בקשות נספרו עד כה, כמה נותרו, ומתי החלון מתאפס. השתמש בזה כדי לבנות מנגנון הגבלת קצב (throttling) בצד הלקוח, כך שהאינטגרציה שלך תאט לפני שתגיע לתגובות `429`.

`GET /api-keys/usage`

**cURL**

```bash
curl "https://api.youraiconnector.com/v1/api-keys/usage" \
  -H "X-API-Key: YOUR_API_KEY"
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/api-keys/usage", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
```

**Python**

```python
import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/api-keys/usage",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
```

**תגובה**

```json
{
  "success": true,
  "usage": {
    "limit": 300,
    "window_seconds": 60,
    "used": 37,
    "remaining": 263,
    "window_resets_at": "2026-06-09T12:01:00.000Z"
  }
}
```

אם עדיין לא נרשמו בקשות בחלון הנוכחי, הניצול מדווח כאפס והתגובה כוללת שדה `note` המסביר מדוע.

---

## החלפת המפתח

מייצר מפתח API חדש ומבטל את הקודם באותו שלב. השתמש בזה אם אתה חושד שהמפתח שלך דלף, או כחלק ממדיניות קבועה של החלפת אישורים.

`POST /api-keys/rotate`

> **המפתח החדש מוצג פעם אחת בלבד.** הוא מוחזר בתגובה זו ולא ניתן יהיה לשחזר אותו במלואו לאחר מכן — שמור אותו בצורה מאובטחת ברגע קבלתו. המפתח הקודם מפסיק לעבוד ברגע שקריאה זו מצליחה, לכן עדכן כל אינטגרציה שהשתמשה בו.

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/api-keys/rotate?apiKey=YOUR_API_KEY"
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/api-keys/rotate", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
// Save data.api_key now — it will not be shown again.
```

**Python**

```python
import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/api-keys/rotate",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
# Save data["api_key"] now — it will not be shown again.
```

**תגובה**

```json
{
  "success": true,
  "api_key": "abcdEFGH1234ijkl5678MNOP9012qrst",
  "message": "API key rotated. The previous key is no longer valid. Store this key now — it will not be shown again."
}
```

---

## ביטול המפתח

מוחק לצמיתות את מפתח ה-API של החשבון שלך. הביטול הוא מיידי: כל בקשה עוקבת המשתמשת במפתח שבוטל — כולל אינטגרציות כגון Make, Zapier או סקריפטים מותאמים אישית — נדחית עם `401`. כדי לשחזר את הגישה ל-API לאחר מכן, צור מפתח חדש מהגדרות החשבון שלך בזמן שאתה מחובר לאפליקציה.

`DELETE /api-keys/current`

> **אין אפשרות לבטל פעולה זו.** בניגוד להחלפה (rotation), ביטול אינו מספק לך מפתח חלופי. בצע ביטול רק כאשר בכוונתך להפסיק את הגישה ל-API (לדוגמה, מפתח שדלף ולא ניתן להחליפו באופן מיידי).

**cURL**

```bash
curl -X DELETE "https://api.youraiconnector.com/v1/api-keys/current" \
  -H "X-API-Key: YOUR_API_KEY"
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/api-keys/current", {
  method: "DELETE",
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
```

**Python**

```python
import requests

res = requests.delete(
    "https://api.youraiconnector.com/v1/api-keys/current",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
```

**תגובה**

```json
{
  "success": true,
  "revoked": true,
  "message": "API key revoked. All requests using it will be rejected immediately."
}
```

אם בחשבון אין מפתח לביטול, התגובה היא `404`.

---

## מפתחות מוגבלי היקף

מפתח מוגבל היקף הוא מפתח API נוסף שאתה יוצר עבור משימה ספציפית אחת, הנושא רק את ההרשאות שהמשימה הזו צריכה. המקרה הקלאסי: אתה רוצה לחבר לוח מחוונים של לקוח, כלי דיווח או סקריפט פנימי לחשבון שלך מבלי למסור מפתח שיכול גם לשלוח הודעות, לשנות את סוכני ה-AI שלך או לרכוש מספר טלפון.

ההגבלה עוברת יחד עם המפתח עצמו, כך שמי שמחזיק בו יכול לעשות רק את מה שהתרת בעת יצירתו.

**מה ניתן להגביל**

| שדה | משמעות |
|---|---|
| `read_only` | `true` (ברירת המחדל) אומר שרק בקשות קריאה מותרות. כל פעולת יצירה, עדכון או מחיקה נדחית. |
| `tags` | רשימת חלקי ה-API שהמפתח רשאי להשתמש בהם, כתובה עם אותם שמות חלקים שאתה רואה בתיעוד זה וב-[סייר ה-API](reference.md) — `Analytics`, `Campaigns`, `Contacts`, `Messages`, `Appointments`, וכן הלאה. רשימה ריקה משמעותה כל החלקים. |
| `sub_account_ids` | באילו חשבונות מנוהלים המפתח רשאי לפעול. ריק משמעו החשבון שלך בלבד; `["*"]` משמעו כל חשבון שאתה מנהל בפועל. הבעלות עדיין נבדקת בכל בקשה. |
| `rate_limit_per_min` | בקשות לדקה עבור מפתח זה, הנספרות בתקציב נפרד כך שלא יוכלו לנצל את המכסה של אינטגרציות אחרות שלך. ברירת המחדל היא `60`, ולא ניתן להגדיר ערך גבוה מ-`300`. |

ניתן גם לתת למפתח תאריך `expires_at` (בפורמט ISO 8601, וחייב להיות בעתיד). לאחר רגע זה, המפתח יפסיק לעבוד מעצמו. השאר זאת ריק והמפתח לעולם לא יפוג עד שתבטל אותו.

> **דחיות הן סופיות.** אם בקשה חורגת ממה שהמפתח מאפשר, היא נדחית במקום שתאושר: פעולת כתיבה עם מפתח לקריאה בלבד מחזירה `403` עם `error_code: "key_read_only"`, וכל דבר מחוץ לחלקים המותרים של המפתח מחזיר `403` עם `error_code: "key_scope_denied"`. אם מפתח מוגבל היקף מקבל `403` בלתי צפוי, נקודת הקצה שקראת לה פשוט אינה נמצאת בתוך ההיקפים שלו — הרחב את הרשאות המפתח או השתמש במפתח הראשי שלך.

> **רק בעל החשבון מנהל מפתחות.** ארבע נקודות קצה אלו דורשות את המפתח הראשי שלך, או סשן של בעלים באפליקציה. מפתח מוגבל היקף לעולם לא יכול להציג, ליצור, לערוך או לבטל מפתחות — כולל את עצמו — כך שלא ניתן להשתמש במפתח מוגבל כדי ליצור מפתח רחב יותר. ניסיון לעשות זאת מחזיר `403` עם `error_code: "key_scope_denied"`. מאותה סיבה, `API Keys` אינו חלק שניתן להעניק: בקשה עבורו מחזירה `400` עם `error_code: "invalid_scopes"`.

### הצגת מפתחות מוגבלי היקף

מחזיר את מפתחות מוגבלי ההיקף של החשבון, מהחדש לישן (עד 200), כולל מפתחות שבוטלו כדי שתוכל לראות מה הוסר ומתי. רק תצוגות מקדימות מוסתרות מוחזרות — הערך של מפתח מוגבל היקף מוצג פעם אחת, בעת היצירה, ולא ניתן לשחזרו לאחר מכן.

`GET /api-keys`

**cURL**

```bash
curl "https://api.youraiconnector.com/v1/api-keys" \
  -H "X-API-Key: YOUR_API_KEY"
```

**תגובה**

```json
{
  "success": true,
  "api_keys": [
    {
      "id": "key_9f2c1a7b4d6e8f0a1b2c3d4e5f60718a",
      "label": "Client dashboard - Acme",
      "key_preview": "abcd...qrst",
      "scopes": {
        "read_only": true,
        "tags": ["Analytics"],
        "sub_account_ids": [],
        "rate_limit_per_min": 60
      },
      "expires_at": null,
      "last_used_at": "2026-08-20T14:03:00.000Z",
      "created_at": "2026-08-14T09:12:00.000Z",
      "revoked_at": null,
      "revoked": false
    }
  ]
}
```

### יצירת מפתח מוגבל היקף

יוצר מפתח מוגדר טווח (scoped key) חדש ומחזיר את ערכו **פעם אחת** בלבד.

`POST /api-keys`

> **המפתח מוצג פעם אחת בלבד.** הוא מופיע בתגובה זו ולא בשום מקום אחר, לעולם — אין דרך לאחזר אותו לאחר מכן. שמור אותו ברגע שאתה מקבל אותו. אם איבדת אותו, בטל אותו וצור מפתח אחר.

**שדות גוף הבקשה** — כולם אופציונליים:

| שדה | סוג | הערות |
|---|---|---|
| `label` | string | שם משלך עבור המפתח, שיוצג ברשימה ובהגדרות. |
| `scopes` | object | ארבעת השדות בטבלה שלעיל. אם תשמיט את האובייקט כולו, תקבל את ברירת המחדל הבטוחה: קריאה בלבד, מוגבל ל-`Analytics`, החשבון שלך בלבד, 60 בקשות לדקה. |
| `expires_at` | ISO 8601 date | תאריך תפוגה אופציונלי, חייב להיות בעתיד. |

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/api-keys" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Client dashboard - Acme",
    "scopes": {
      "read_only": true,
      "tags": ["Analytics"],
      "sub_account_ids": [],
      "rate_limit_per_min": 60
    }
  }'
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/api-keys", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    label: "Client dashboard - Acme",
    scopes: { read_only: true, tags: ["Analytics"] },
  }),
});
const data = await res.json();
// Save data.api_key now — it will not be shown again.
```

**Python**

```python
import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/api-keys",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "label": "Client dashboard - Acme",
        "scopes": {"read_only": True, "tags": ["Analytics"]},
    },
)
data = res.json()
# Save data["api_key"] now — it will not be shown again.
```

**תגובה** — `201 Created`

```json
{
  "success": true,
  "api_key": "abcdEFGH1234ijkl5678MNOP9012qrst",
  "key": {
    "id": "key_9f2c1a7b4d6e8f0a1b2c3d4e5f60718a",
    "label": "Client dashboard - Acme",
    "key_preview": "abcd...qrst",
    "scopes": {
      "read_only": true,
      "tags": ["Analytics"],
      "sub_account_ids": [],
      "rate_limit_per_min": 60
    },
    "expires_at": null,
    "revoked": false
  },
  "message": "Store this key now — it is shown once and cannot be retrieved again."
}
```

כמה פרטים שכדאי לדעת כשבונים מול זה:

- **השמטת `scopes` אינה זהה לשליחת רשימת `tags` ריקה.** השאר את `scopes` בחוץ לחלוטין ותקבל את ברירת המחדל הבטוחה (קריאה בלבד, `Analytics` בלבד). שלח `"tags": []` במכוון והמפתח יוכל להשתמש בכל סעיף — זה נקרא כבקשה מכוונת למפתח ללא הגבלות.
- **`read_only` נשאר `true` אלא אם תשלח במפורש `false`.** שגיאת הקלדה או דגל חסר לעולם לא יכולים ליצור בטעות מפתח בעל הרשאות כתיבה.

### עדכון מפתח מוגדר טווח

משנה את התווית, הטווחים ו/או תאריך התפוגה של מפתח. שלח כל שילוב של השלושה; שליחת אף אחד מהם תחזיר `400`.

`PATCH /api-keys/{id}`

ה-`{id}` הוא ה-`id` של המפתח מתוך הרשימה (ערך ה-`key_...`), לעולם לא המפתח עצמו.

> **טווחים מוחלפים, לא ממוזגים.** כל מה שתשלח הופך לקבוצת ההרשאות המלאה של המפתח. זה מכוון: צמצום טווח של מפתח לעולם לא ישאיר בטעות את הגישה הרחבה הישנה במקומה. תמיד שלח את אובייקט ה-`scopes` המלא שאתה רוצה, לא רק את השדה שאתה משנה.

ערך המפתח לעולם לא משתנה. אין אפשרות לסיבוב מפתחות (rotate-in-place) עבור מפתח מוגדר טווח — כדי להחליף מפתח, צור מפתח חדש ובטל את הישן, כך שהגישה של אישור (credential) לעולם לא תוכל להשתנות תחת אינטגרציה שעדיין מחזיקה בו.

**cURL**

```bash
curl -X PATCH "https://api.youraiconnector.com/v1/api-keys/key_9f2c1a7b4d6e8f0a1b2c3d4e5f60718a" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Client dashboard - Acme (read-only)",
    "scopes": {
      "read_only": true,
      "tags": ["Analytics", "Campaigns"],
      "sub_account_ids": [],
      "rate_limit_per_min": 30
    }
  }'
```

**תגובה**

```json
{
  "success": true,
  "key": {
    "id": "key_9f2c1a7b4d6e8f0a1b2c3d4e5f60718a",
    "label": "Client dashboard - Acme (read-only)",
    "key_preview": "abcd...qrst",
    "scopes": {
      "read_only": true,
      "tags": ["Analytics", "Campaigns"],
      "sub_account_ids": [],
      "rate_limit_per_min": 30
    },
    "expires_at": null,
    "last_used_at": "2026-08-20T14:03:00.000Z",
    "created_at": "2026-08-14T09:12:00.000Z",
    "revoked_at": null,
    "revoked": false
  }
}
```

אם אין מפתח עם מזהה (id) כזה בחשבונך, התגובה תהיה `404`.

### ביטול מפתח בעל טווח (scoped key)

הביטול הוא מיידי: הבקשה הבאה שתשתמש במפתח זה תידחה עם `401`. המפתח הראשי שלך וכל מפתח אחר בעל טווח לא יושפעו מכך.

`DELETE /api-keys/{id}`

המפתח נשאר ברשימה שלך כשהוא מסומן כ-`"revoked": true`, כך שיישמר אצלך תיעוד של מה שהיה קיים ולאילו משאבים הייתה לו גישה. ביטול מפתח שכבר בוטל יסתיים בהצלחה ולא ישנה דבר.

**cURL**

```bash
curl -X DELETE "https://api.youraiconnector.com/v1/api-keys/key_9f2c1a7b4d6e8f0a1b2c3d4e5f60718a" \
  -H "X-API-Key: YOUR_API_KEY"
```

**תגובה**

```json
{
  "success": true,
  "revoked": true,
  "id": "key_9f2c1a7b4d6e8f0a1b2c3d4e5f60718a",
  "message": "API key revoked. All requests using it will be rejected immediately."
}
```

---

## שגיאות API של מפתחות API

נקודות קצה של מפתחות API מחזירות את מעטפת השגיאה הסטנדרטית:

```json
{
  "success": false,
  "error": "No API key found for this account"
}
```

בנקודת קצה של מפתח API, מפתח חסר או לא תקין מחזיר `401` וחשבון ללא מפתח רשום מחזיר `404`. הקודים המשותפים שכל נקודת קצה יכולה להחזיר — `400`, `403` (התוכנית שלך אינה כוללת גישת API), `429` (מגבלת קצב) ו-`500` — מפורטים יחד עם הנחיות לניסיון חוזר ב-[שגיאות ועימוד](errors-and-pagination.md).

נקודות הקצה של מפתחות בעלי טווח מוסיפות מספר קודים בעלי שם בשדה `error_code` כדי שתוכל להבדיל בין המקרים:

| `error_code` | סטטוס | מה קרה |
|---|---|---|
| `key_read_only` | `403` | מפתח לקריאה בלבד ניסה לבצע פעולת כתיבה. |
| `key_scope_denied` | `403` | המפתח אינו מורשה בנקודת קצה זו או בחשבון מנוהל זה — או שמפתח בעל טווח ניסה לנהל מפתחות API, דבר שלעולם אינו מותר. |
| `invalid_scopes` | `400` | הטווחים המבוקשים כללו את המקטע `API Keys`. מפתחות אינם יכולים לנהל מפתחות. |
| `404` | `404` | לא קיים מפתח עם מזהה זה בחשבונך. |

---

## צעדים הבאים

- [אימות](authentication.md) — ארבע הדרכים לאימות בקשה, וכיצד נאכפים טווחי מפתחות.
- [שגיאות ומגבלות קצב](errors-and-pagination.md) — קודי סטטוס והמגבלה של 300 בקשות לדקה.