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

# מדריך התחלה מהירה ל-API

> צרו חשבון שירות ומפתח API ב-Developer Hub, בצעו אימות באמצעות Basic auth ושלחו את הבקשה הראשונה שלכם ל-Living Security Public API.

צרו חשבון שירות ומפתח API ב-Developer Hub, ולאחר מכן שלחו את הבקשה הראשונה
שלכם. מדריך התחלה מהירה זה משתמש באימות באמצעות מפתח API; אין צורך בלקוח
OAuth. אם האינטגרציה שלכם דורשת אסימוני גישה קצרי טווח של OAuth, ראו [אימות](/he/developers/v1/authentication).

## דרישות מקדימות

* גישת מנהל ל-Living Security לוח מחוונים.
* Developer Hub גלוי תחת **הגדרות → Integrations & Developers →
  Developer Hub**.

## יצירת פרטי הגישה

<Steps>
  <Step title="יצירת חשבון שירות">
    ב-Developer Hub, פתחו את הלשונית **Service accounts** וצרו
    חשבון. תנו לו שם תיאורי (לדוגמה `reporting-pipeline`) והעניקו
    את ההרשאות שהמפתחות שלו רשאים להשתמש בהן — עבור מדריך זה, `organization:read`
    מספיק.

    הרשאות החשבון הן התקרה עבור כל מפתח שנוצר תחתיו:
    מפתח לעולם אינו יכול לבצע יותר ממה שחשבון השירות שלו מתיר.
  </Step>

  <Step title="יצירת מפתח API">
    פתחו את עמוד הפרטים של חשבון השירות וצרו מפתח. בחרו את
    ההרשאות הנדרשות למפתח הספציפי הזה (תת-קבוצה של הרשאות החשבון) ואת
    תוקפו — 30, 90 או 365 ימים, או תקופה מותאמת אישית. הגדרת תוקף היא
    חובה.

    הסוד של המפתח מתחיל ב-`lsk_live_` ומוצג **פעם אחת בלבד**. העתיקו אותו
    מיד למנהל סודות; לא ניתן לאחזר אותו מאוחר יותר.

    <Warning>
      לעולם אין לשמור סודות של מפתחות API במערכת בקרת גרסאות או להטמיע אותם בקוד
      בצד הלקוח. כל מי שמחזיק בסוד יכול לפעול עם הרשאות המפתח.
    </Warning>
  </Step>

  <Step title="בחירת האזור">
    פנו למארח `/v1` האזורי התואם למיקום הנתונים של הארגון. מפתחות
    מאומתים רק במארח זה.

    | אזור | כתובת בסיס |
    | - | - |
    | ארה״ב | `https://api.us-east-1.livingsecurity.ai/v1` |
    | האיחוד האירופי | `https://api.eu-west-1.livingsecurity.ai/v1` |

    אם אינכם בטוחים באיזה מארח להשתמש, ראו [אזורים](/he/developers/v1/regions). מפתח תקף שנשלח לאזור האחר נכשל עם `unauthorized`. השתמשו
    ברשימה הנפתחת של האזור בדוגמה שלהלן כדי להחליף את המארח.
  </Step>

  <Step title="שליחת הבקשה הראשונה">
    טענו את `LIVING_SECURITY_API_KEY` ממנהל הסודות אל הסביבה
    של התהליך ששולח את הבקשה. הדוגמאות שלהלן קוראות אותו מבלי להטמיע
    סוד בקוד המקור. עבור Python, התקינו תחילה את `requests`.

    פנו ל-API כשהסוד מוזן בשדה הסיסמה או בשדה שם המשתמש של HTTP Basic auth
    — שתי האפשרויות תקפות, ולכן לקוחות שדורשים מילוי של שני השדות (כגון מחבר Web של
    Power BI) יכולים להזין ערך זמני כמו `apikey` בשדה השני.

    <CodeGroup>
      ```bash cURL theme={null}
      curl --fail-with-body --connect-timeout 5 --max-time 30 \
        https://api.eu-west-1.livingsecurity.ai/v1/organization \
        -u "apikey:${LIVING_SECURITY_API_KEY:?Set LIVING_SECURITY_API_KEY}" \
        -H "Living-Security-Version: 2026-07-01"
      ```

      ```bash cURL (key as username) theme={null}
      curl --fail-with-body --connect-timeout 5 --max-time 30 \
        https://api.eu-west-1.livingsecurity.ai/v1/organization \
        -u "${LIVING_SECURITY_API_KEY:?Set LIVING_SECURITY_API_KEY}:" \
        -H "Living-Security-Version: 2026-07-01"
      ```

      ```python Python theme={null}
      import os
      import requests

      BASE = "https://api.eu-west-1.livingsecurity.ai/v1"

      response = requests.get(
          f"{BASE}/organization",
          auth=("apikey", os.environ["LIVING_SECURITY_API_KEY"]),
          headers={"Living-Security-Version": "2026-07-01"},
          timeout=(5, 30),
          allow_redirects=False,
      )
      response.raise_for_status()
      if response.status_code != 200:
          raise RuntimeError("Unexpected response; check your regional API URL")
      print(response.json())
      ```
    </CodeGroup>

    תגובה מוצלחת מחזירה את הארגון שלכם:

    ```json Response theme={null}
    {
      "id": "1e2f3a4b-5c6d-4e7f-8a9b-0c1d2e3f4a5b",
      "object": "organization",
      "name": "Example Corp",
      "region": "eu",
      "plan": "enterprise",
      "subscription_status": "active",
      "created_at": "2024-03-12T18:04:11.000Z"
    }
    ```

    <Check>
      אם קיבלתם תגובה זו, פרטי הגישה שלכם תקינים. הבקשה מופיעה גם בלשונית
      **Request logs** של Developer Hub תוך רגעים ספורים.
    </Check>
  </Step>
</Steps>

<Tip>
  אימות Bearer עם אותו סוד (`Authorization: Bearer
    lsk_live_...`) פועל גם הוא. Basic auth קיים כדי שכלים שתומכים רק
  בשם משתמש/סיסמה — כמו מחבר Web של Power BI — יוכלו להתחבר.
</Tip>

## כיצד פועל האימות

* **פרטי הגישה קובעים את הארגון.** בקשות `/v1` אינן כוללות
  בורר דיירים: אין מקטע נתיב של ארגון ואין כותרת ארגון.
  שליחת כותרת `x-organization-id` נדחית עם `invalid_request`.
  המארח חייב להתאים לאזור של אותו ארגון. ראו
  [אזורים](/he/developers/v1/regions).
* **הרשאות נבדקות לכל פעולה.** כל פעולת `/v1` דורשת
  הרשאה בעלת שם (לדוגמה, `GET /v1/organization` דורשת
  `organization:read`). מפתח שחסרה לו ההרשאה מקבל `403` עם הקוד
  `insufficient_permission`.
* **מפתחות פגים ואפשר להחליף אותם ללא השבתה.** ראו
  [מפתחות API](/he/developers/developer-hub/api-keys) לפרטים על החלפה עם חלון
  חפיפה.

## קריאת תגובות שגיאה

כל שגיאת `/v1` היא `application/problem+json`
([RFC 9457](https://www.rfc-editor.org/rfc/rfc9457)) עם קוד
מכונה יציב. לדוגמה, בקשה עם פרטי גישה חסרים או לא מוכרים מחזירה:

```json 401 Unauthorized theme={null}
{
  "type": "https://docs.livingsecurity.com/developers/v1/errors/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "No valid API credential was provided.",
  "code": "unauthorized",
  "request_id": "req_...",
  "doc_url": "https://docs.livingsecurity.com/developers/v1/errors/unauthorized",
  "retryable": false
}
```

הסתעפו לפי `code`, ולעולם לא לפי `detail`. פעלו לפי `doc_url` לשלבי
הפתרון, וצרפו את `request_id` בפנייה לתמיכה — הוא תואם לכותרת התגובה
`Request-Id` וליומני הבקשות של Developer Hub. קבוצת הקודים המלאה
נמצאת ב[מדריך השגיאות](/he/developers/v1/errors/overview).

## גרסאות חוזה

כל תגובה משקפת את גרסת החוזה ששירתה אותה בכותרת
`Living-Security-Version`, לצד כותרת `Request-Id` לצורך
התאמה.

אפשר לקבע בקשה לגרסת חוזה שפורסמה לפי תאריך:

<CodeGroup>
  ```bash cURL theme={null}
  curl --fail-with-body --connect-timeout 5 --max-time 30 \
    https://api.eu-west-1.livingsecurity.ai/v1/organization \
    -u "apikey:${LIVING_SECURITY_API_KEY:?Set LIVING_SECURITY_API_KEY}" \
    -H "Living-Security-Version: 2026-07-01"
  ```
</CodeGroup>

הגרסה נקבעת בסדר הבא: כותרת הבקשה אם קיימת, אחרת
ברירת המחדל המקובעת של חשבון השירות, ואחרת הגרסה האחרונה שפורסמה.
בקשת גרסה שלא פורסמה (או שעבר תאריך הפסקת התמיכה שלה)
מחזירה `400` עם הקוד `unsupported_version`. הגרסאות שפורסמו והשינויים
בהן מפורטים ב[יומן השינויים של ה-API](/he/developers/v1/changelog).

## פתרון בעיות בבקשה הראשונה

| תוצאה | הפעולה הבאה |
| - | - |
| `401 unauthorized` | בדקו את הסוד, את תוקפו ואת האזור של הארגון. אל תנסו מארחים אחרים עם פרטי גישה פעילים. |
| `403 insufficient_permission` | הענקו את `organization:read` הן לחשבון השירות והן למפתח שלו. |
| `400 unsupported_version` | בחרו גרסה שפורסמה מתוך [יומן השינויים](/he/developers/v1/changelog). |
| `429 rate_limited` | המתינו ל-`Retry-After`; פעלו לפי [דוגמת הניסיון החוזר התחום](/he/developers/v1/rate-limits). |
| פסק זמן ברשת | בדקו את הקישוריות ונסו שוב את פעולת הקריאה הזו במסגרת תקציב הניסיונות החוזרים של היישום שלכם. |

לשגיאות אחרות, פעלו לפי `doc_url` של התגובה. שמרו את `Request-Id` עבור
התמיכה; לעולם אל תכללו את כותרת Authorization או את מפתח ה-API שלכם בפנייה.

## השלבים הבאים

<CardGroup cols={2}>
  <Card title="אזורים" href="/he/developers/v1/regions">
    בחרו את מארח `/v1` של ארה״ב או של האיחוד האירופי עבור הארגון.
  </Card>

  <Card title="עימוד" href="/he/developers/v1/pagination">
    עברו על רשימות באמצעות `page_token` ועטיפת הרשימה.
  </Card>

  <Card title="מגבלות קצב" href="/he/developers/v1/rate-limits">
    הבינו את תקציבי הבקשות וטפלו בתגובות `429`.
  </Card>

  <Card title="מדריך שגיאות" href="/he/developers/v1/errors/overview">
    כל קוד שגיאה, סטטוס ה-HTTP שלו ואופן הפתרון.
  </Card>

  <Card title="Developer Hub" href="/he/developers/developer-hub/overview">
    ניהול חשבונות שירות, מפתחות API ויומני בקשות.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.