# אימות

כל בקשת API חייבת לשאת את מפתח ה-API שלך כדי ש-<span data-t="appName">Your AI Connector</span> תדע שזה אתה ועל איזה חשבון לפעול. באפשרותך לשלוח את המפתח בארבע דרכים שונות — כולן עובדות בכל נקודת קצה המקבלת אימות באמצעות מפתח API, לכן בחר את הדרך המתאימה ביותר להגדרה שלך.

גישת API היא תכונה בתשלום. אם התוכנית שלך אינה כוללת אותה, בקשות יידחו עם `403` גם כאשר המפתח עצמו תקין — ראה [שער התכונות בתשלום](#the-paid-feature-gate) להלן. כדי ליצור מפתח, ראה [גישת API](../integrations/api-access.md).

> **HTTPS בלבד.** כל הבקשות חייבות להשתמש בחיבור מאובטח. בקשות HTTP רגילות נדחות עוד לפני שהאימות מתבצע.

---

## ארבע השיטות במבט חטוף

| שיטה | מוביל | מתי להשתמש |
|---|---|---|
| פרמטר שאילתה | `?apiKey=YOUR_API_KEY` | בדיקות מהירות וכתובות URL בדפדפן |
| כותרת | `X-API-Key: YOUR_API_KEY` | אינטגרציות בייצור |
| כותרת Bearer | `Authorization: Bearer YOUR_API_KEY` | אינטגרציות בייצור |
| אסימון Firebase ID | `Authorization: Bearer <ID token>` | הפעלות אפליקציה של צד ראשון בלבד |

כאשר קיימת יותר משיטה אחת, פרמטר השאילתה גובר, לאחר מכן כותרת ה-`X-API-Key`, ולאחריה אסימון ה-bearer. בפועל, תמיד תשלח רק אחת.

---

## 1. פרמטר שאילתה — `?apiKey=`

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

**cURL**

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

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/contacts?apiKey=YOUR_API_KEY");
const data = await res.json();
```

**Python**

```python
import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/contacts",
    params={"apiKey": "YOUR_API_KEY"},
)
data = res.json()
```

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

---

## 2. כותרת `X-API-Key`

שלח את המפתח בכותרת ייעודית. זה שומר עליו מחוץ ל-URL וזו הבחירה המומלצת עבור סביבת ייצור.

**cURL**

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

**JavaScript**

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

**Python**

```python
import requests

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

---

## 3. כותרת `Authorization: Bearer`

ניתן גם להעביר את המפתח כ-bearer token סטנדרטי. זה שימושי כאשר ללקוח ה-HTTP או ל-framework שלך כבר יש תמיכה מובנית בכותרות `Authorization`.

**cURL**

```bash
curl "https://api.youraiconnector.com/v1/contacts" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/contacts", {
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
  },
});
const data = await res.json();
```

**Python**

```python
import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/contacts",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
)
data = res.json()
```

ה-API מבדיל באופן אוטומטי בין מפתח ה-API שלך לבין אסימון התחברות (login token), לכן שיטה זו פועלת בדיוק כמו `X-API-Key`.

---

## 4. אסימון Firebase ID (עבור צד ראשון בלבד)

אם אתה בונה אפליקציית צד ראשון שמחברת משתמשים דרך ההתחברות של <span data-t="appName">Your AI Connector</span> עצמו, באפשרותך להעביר את אסימון ה-Firebase ID של המשתמש המחובר כ-bearer token במקום מפתח API:

```
Authorization: Bearer <Firebase ID token>
```

האסימון מאומת בכל בקשה וממופה לחשבון המחובר. **שיטה זו מיועדת להפעלות של אפליקציות צד ראשון בלבד** — לא ניתן להנפיק אסימונים אלו מאינטגרציה חיצונית, ואין דרך להשיג אחד מבלי לעבור את תהליך ההתחברות הרגיל של האפליקציה. עבור אינטגרציות שרת-לשרת וצד שלישי, השתמש במפתח API (שיטות 1–3).

---

## מתי להשתמש במה

- **בדיקות מהירות וסקריפטים חד-פעמיים** → פרמטר שאילתה (`?apiKey=`). הכי מהיר להקלדה, עובד בדפדפן.
- **אינטגרציות בייצור וקריאות שרת-לשרת** → `X-API-Key` או `Authorization: Bearer YOUR_API_KEY`. שומר על המפתח מחוץ לכתובות URL ויומני רישום (logs).
- **אפליקציות צד ראשון עם משתמש <span data-t="appName">Your AI Connector</span> מחובר** → `Authorization: Bearer <Firebase ID token>`.

---

## טווחי מפתח (Key scopes)

לחשבונך יש **מפתח API ראשי** אחד — זה שנמצא תחת **הגדרות ← אינטגרציות ← מפתח API**. יש לו גישה מלאה לכל הפעולות שהחשבון יכול לבצע.

באפשרותך גם ליצור **מפתחות מוגבלי טווח (scoped keys)** נוספים: מפתחות בעלי שם שגישתם מוגבלת רק לחלקים ב-API שתבחר, לדוגמה מפתח לקריאה בלבד המוגבל ל-Analytics עבור לוח מחוונים של דוחות. מפתח מוגבל טווח נשלח בדיוק כמו המפתח הראשי (באחת משיטות 1–3 לעיל), אך הוא נבדק מול ההרשאות שלו בכל בקשה:

- **מחוץ לאזורים המורשים שלו, הגישה נדחית.** פעולת כתיבה עם מפתח לקריאה בלבד, או קריאה למקטע שהמפתח לא קיבל עבורו הרשאה, יחזירו `403` — `key_read_only` או `key_scope_denied` בשדה `error_code`. הבדיקה קפדנית במכוון: כל מה שאינו נמצא בבירור בתוך האזורים המורשים של המפתח נדחה במקום להיות מאושר, לכן אם אתה רואה אחת מהשגיאות `403`, המפתח פשוט אינו מכסה את נקודת הקצה (endpoint) הזו.
- **יש לו תקציב מגבלת קצב (rate-limit) משלו.** מפתח מוגבל טווח נספר בנפרד מהמפתח הראשי שלך, כך שלוח מחוונים עמוס המשתמש במפתח מוגבל טווח לא ינצל את המכסה ששאר האינטגרציות שלך תלויות בה. אתה בוחר את התקציב לדקה בעת יצירת המפתח.
- **הוא אינו יכול לנהל מפתחות API.** רק בעל החשבון — כשהוא מחובר, או באמצעות המפתח הראשי — יכול להציג, ליצור, לערוך, לרענן או לבטל מפתחות. מפתח מוגבל טווח לעולם לא יוכל ליצור לעצמו מפתח בעל הרשאות רחבות יותר.

ראה [מפתחות API](api-keys.md) למידע על אופן היצירה, העריכה והביטול של מפתחות מוגבלי טווח.

---

## חסימת תכונות בתשלום

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

```json
{
  "success": false,
  "error_code": 403,
  "error": "This action requires the \"api_access\" feature, which is not enabled for this account."
}
```

If you see this, check your plan or contact [<span data-t="supportEmail">hi@youraiconnector.com</span>](mailto:hi@youraiconnector.com). A missing or wrong key returns `401` instead:

```json
{
  "success": false,
  "error_code": 401,
  "error": "Invalid API key"
}
```

---

## שמירה על אבטחת המפתח שלך

- **התייחס למפתח כאל סיסמה.** המפתח הראשי שלך מעניק גישה מלאה לחשבונך. אם עליך למסור מפתח לכלי או לאדם שזקוק רק לחלק מהגישה, צור במקום זאת מפתח מוגבל טווח — ראה [טווחי מפתח](#key-scopes).
- **שמור אותו בצד השרת.** לעולם אל תטמיע אותו ב-JavaScript של דפדפן, בחבילת אפליקציה לנייד, או בכל קוד שמשתמש קצה יכול לקרוא.
- **אחסן אותו במנהל סודות (secret manager)** או בהגדרות צד-שרת, לא בבקרת המקור (source control).
- **רענן אותו אם הוא דלף.** צור מפתח חדש מלוח המחוונים או קרא ל-`POST https://api.youraiconnector.com/v1/api-keys/rotate` — פעולה זו מבטלת מיד את המפתח הישן. ראה [מפתחות API](api-keys.md).
- **השתמש תמיד ב-HTTPS** כדי שהמפתח יהיה מוצפן במעבר.

---

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

- [תחילת עבודה](getting-started.md) — הבקשה הראשונה שלך ומדריכי המשאבים.
- [שגיאות ועימוד](errors-and-pagination.md) — טיפול בכשלים ודפדוף בין תוצאות.
- [מפתחות API](api-keys.md) — החלפה, ביטול ובדיקת השימוש במפתח שלך.