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

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

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

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

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

יצירת חשבון שירות

ב-Developer Hub, פתחו את הלשונית Service accounts וצרו חשבון. תנו לו שם תיאורי (לדוגמה reporting-pipeline) והעניקו את ההרשאות שהמפתחות שלו רשאים להשתמש בהן — עבור מדריך זה, organization:read מספיק.הרשאות החשבון הן התקרה עבור כל מפתח שנוצר תחתיו: מפתח לעולם אינו יכול לבצע יותר ממה שחשבון השירות שלו מתיר.

יצירת מפתח API

פתחו את עמוד הפרטים של חשבון השירות וצרו מפתח. בחרו את ההרשאות הנדרשות למפתח הספציפי הזה (תת-קבוצה של הרשאות החשבון) ואת תוקפו — 30, 90 או 365 ימים, או תקופה מותאמת אישית. הגדרת תוקף היא חובה.הסוד של המפתח מתחיל ב-lsk_live_ ומוצג פעם אחת בלבד. העתיקו אותו מיד למנהל סודות; לא ניתן לאחזר אותו מאוחר יותר.

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

בחירת האזור

פנו למארח /v1 האזורי התואם למיקום הנתונים של הארגון. מפתחות מאומתים רק במארח זה.

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

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

שליחת הבקשה הראשונה

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

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"

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"

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())

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

Response

{
  "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"
}

אם קיבלתם תגובה זו, פרטי הגישה שלכם תקינים. הבקשה מופיעה גם בלשונית Request logs של Developer Hub תוך רגעים ספורים.

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

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

פרטי הגישה קובעים את הארגון. בקשות /v1 אינן כוללות בורר דיירים: אין מקטע נתיב של ארגון ואין כותרת ארגון. שליחת כותרת x-organization-id נדחית עם invalid_request. המארח חייב להתאים לאזור של אותו ארגון. ראו אזורים.
הרשאות נבדקות לכל פעולה. כל פעולת /v1 דורשת הרשאה בעלת שם (לדוגמה, GET /v1/organization דורשת organization:read). מפתח שחסרה לו ההרשאה מקבל 403 עם הקוד insufficient_permission.
מפתחות פגים ואפשר להחליף אותם ללא השבתה. ראו מפתחות API לפרטים על החלפה עם חלון חפיפה.

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

כל שגיאת /v1 היא application/problem+json (RFC 9457) עם קוד מכונה יציב. לדוגמה, בקשה עם פרטי גישה חסרים או לא מוכרים מחזירה:

401 Unauthorized

{
  "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. קבוצת הקודים המלאה נמצאת במדריך השגיאות.

גרסאות חוזה

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

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"

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

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

תוצאה	הפעולה הבאה
`401 unauthorized`	בדקו את הסוד, את תוקפו ואת האזור של הארגון. אל תנסו מארחים אחרים עם פרטי גישה פעילים.
`403 insufficient_permission`	הענקו את `organization:read` הן לחשבון השירות והן למפתח שלו.
`400 unsupported_version`	בחרו גרסה שפורסמה מתוך יומן השינויים.
`429 rate_limited`	המתינו ל-`Retry-After`; פעלו לפי דוגמת הניסיון החוזר התחום.
פסק זמן ברשת	בדקו את הקישוריות ונסו שוב את פעולת הקריאה הזו במסגרת תקציב הניסיונות החוזרים של היישום שלכם.

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

השלבים הבאים

אזורים

בחרו את מארח /v1 של ארה״ב או של האיחוד האירופי עבור הארגון.

עימוד

עברו על רשימות באמצעות page_token ועטיפת הרשימה.

מגבלות קצב

הבינו את תקציבי הבקשות וטפלו בתגובות 429.

מדריך שגיאות

כל קוד שגיאה, סטטוס ה-HTTP שלו ואופן הפתרון.

Developer Hub

ניהול חשבונות שירות, מפתחות API ויומני בקשות.

מרכז המפתחים

API ציבורי v1

מדריך עזר ל-API v1

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

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

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

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

גרסאות חוזה

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

השלבים הבאים

אזורים

עימוד

מגבלות קצב

מדריך שגיאות

Developer Hub

מרכז המפתחים

API ציבורי v1

מדריך עזר ל-API v1

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

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

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

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

​גרסאות חוזה

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

​השלבים הבאים

אזורים

עימוד

מגבלות קצב

מדריך שגיאות

Developer Hub

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

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

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

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

גרסאות חוזה

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

השלבים הבאים