Legacy Public API

מדריך זה עוסק באינטגרציות /api/v1 קיימות המחליפות מפתח גישה ל-API באסימון נושא (bearer token). פרטי הגישה ופורמט הבקשות שלהן שונים מאלה של ה-Public API של /v1. לאינטגרציה חדשה, התחילו במדריך התחלה מהירה ל-API ובאימות. ה-API החדש של /v1 משתמש במפתחות API של חשבון שירות (service account) או באסימוני גישה של OAuth.

לפני שמתחילים

נדרשים הפריטים הבאים:

גישה ל-Living Security המאפשרת ניהול של מפתחות גישה ל-API
מפתח גישה ל-API שנוצר תחת Settings → Access Keys
סוד מפתח הגישה החד-פעמי המוצג בעת יצירת פרטי הגישה
מזהה המנפיק של ה-API (API issuer ID) שסופק על ידי Living Security יחד עם פרטי הגישה ל-Public API
כתובת הבסיס האזורית של הארגון שאותו אתם משלבים
סביבת הרצה בצד השרת ומנהל סודות (secret manager)

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

תיבת הדו-שיח Access Keys מציגה את הסוד החד-פעמי, אך אינה מציגה את מזהה המנפיק של ה-API. אם Living Security לא סיפקה לכם את מזהה המנפיק יחד עם פרטי הגישה ל-Public API, בקשו אותו מהתמיכה של Living Security. מזהה המנפיק אינו מזהה מפתח הגישה ואינו מזהה הארגון.

מארחים אזוריים

החוזה הקודם (legacy) משתמש במארחי הייצור האזוריים הבאים של /api/v1:

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

השתמשו באזור שהוקצה לארגון ב-Living Security. אל תחליפו אזורים כדי לעקוף שגיאת הרשאה או זמינות.

משאבים קודמים (Legacy)

משאב	פעולות נתמכות
אנשים	חיפוש אנשים בארגון ואחזור החברוּת של אדם
מפתחות גישה ל-API	יצירה, הצגת רשימה, רוטציה וביטול של מפתחות גישה ל-API

להצגת הרשימה המלאה של הפעולות, הפרמטרים, הבקשות, התגובות והסכמות, היעזרו ב-Developers → Public API Reference. אם פעולה אינה מופיעה שם, היא אינה חלק מ-Public API כרגע.

אימות

הגישה ל-Public API מתבצעת בשני שלבים:

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

כותרות הבקשה הנדרשות הן:

Authorization: Bearer <access-token>
x-organization-id: <organization-id>

כותרת הארגון חייבת להיות הארגון שהוחזר בהחלפת מפתח הגישה. מפתח אינו מעניק הרשאת גישה למזהה ארגון שרירותי.

TypeScript SDK

התקינו את הגרסה הראשית הנוכחית:

npm install @livingsecurity/sdk@^1

לאחר מכן בצעו את החלפת המפתח והגדירו את ה-SDK:

import { configure, exchangeAccessKey } from "@livingsecurity/sdk";

const accessKeySecret = process.env.LS_API_ACCESS_KEY_SECRET;
const apiIssuerId = process.env.LS_API_ISSUER_ID;

if (!accessKeySecret || !apiIssuerId) {
  throw new Error("LS_API_ACCESS_KEY_SECRET and LS_API_ISSUER_ID are required");
}

const { accessToken, organizationId } = await exchangeAccessKey(
  accessKeySecret,
  apiIssuerId,
);

configure({
  baseUrl: "https://api.us-east-1.livingsecurity.ai/api/v1",
  accessToken,
  organizationId,
});

עבור ארגון באיחוד האירופי, השתמשו בכתובת הבסיס של האיחוד האירופי. החלפת המפתח באמצעות ה-SDK מיועדת לסביבות הרצה של Node.js בצד השרת.

בקשת REST ישירה

אם אתם מבצעים את ההחלפה מחוץ ל-SDK, שלחו את אסימון הנושא ואת מזהה הארגון בכל בקשה:

curl --request GET \
  "https://api.us-east-1.livingsecurity.ai/api/v1/people/search?limit=1" \
  --header "Authorization: Bearer $LIVING_SECURITY_BEARER_TOKEN" \
  --header "x-organization-id: $LIVING_SECURITY_ORG_ID" \
  --header "Accept: application/json"

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

מחזור החיים של מפתח גישה

תנו למפתחות שמות לפי האינטגרציה או האוטומציה שבבעלותה הם נמצאים.
בחרו את ההיקפים (scopes) בעלי ההרשאות המינימליות שמוצעים בטופס מפתח הגישה.
שמרו את הסוד החד-פעמי מיד; לא ניתן לאחזר אותו לאחר היצירה או הרוטציה.
בצעו רוטציה למפתח דרך Settings → Access Keys והטמיעו את המפתח החלופי לפני ביטול פרטי הגישה הישנים.
בטלו מפתחות שאינם בשימוש או שהסוד שלהם עלול להיחשף.
השתמשו במפתחות חשבון שירות עבור אינטגרציות שאינן אנושיות, כאשר סוג מפתח זה זמין בארגון שלכם.

דפדוף

חיפוש אנשים תומך בפרמטרים limit, cursor, offset ו-includeTotal. לסריקה רציפה מומלץ להשתמש בסמן (cursor) שהוחזר בתגובה הקודמת.

limit ברירת המחדל היא 50 והוא מקבל ערכים בין 1 ל-100.
cursor ממשיך מתגובה קודמת.
offset מדלג על מספר רשומות וברירת המחדל שלו היא 0.
includeTotal=true מבקש ספירה מדויקת של התוצאות המסוננות; השמיטו אותו כשאין צורך בספירה.

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

שגיאות

שגיאות JSON מתועדות מופיעות בצורה הכללית הבאה:

{
  "statusCode": 400,
  "message": "Validation failed",
  "error": "Bad Request"
}

message יכול להיות מחרוזת או מערך של הודעות אימות.

סטטוס	משמעות	תגובה
`400`	פרמטרים או גוף בקשה לא תקינים	תקנו את שגיאות האימות המצוינות
`401`	אסימון הנושא חסר, לא תקין או שפג תוקפו	בצעו שוב החלפה של מפתח הגישה ונסו פעם אחת נוספת
`403`	לפרטי הגישה אין הרשאה או גישה לארגון	בדקו את היקפי המפתח ואת הקשר הארגון
`404`	המשאב אינו קיים בארגון המורשה	ודאו את מזהה המשאב ואת הארגון
`408`	הבקשה חרגה ממגבלת הזמן	נסו שוב עם השהיה אקספוננציאלית מוגבלת
`429`	הגעתם למגבלת הקצב	המתינו לפחות כמה שמצוין ב-`Retry-After`, אם קיים
`5xx`	כשל זמני בשירות	נסו שוב קריאות בטוחות עם השהיה אקספוננציאלית מוגבלת

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

תאימות והוצאה משימוש

V1 מתפתח כברירת מחדל באופן מוסיף בלבד. על הלקוחות להתעלם משדות לא מוכרים בתגובה. שינוי שובר תאימות מחייב נתיב מעבר מתועד; פעולות שהוצאו משימוש נשארות במסמך העזר עם הסיבה, התחליף כשקיים ותאריך הסיום (sunset) במהלך תקופת המעבר. נעלו את ה-SDK לגרסה ראשית תואמת ועיינו בהערות הגרסה שלו לפני שדרוג. יש לראות במסמך העזר Public API Reference שנוצר אוטומטית, ולא בלקוחות האפליקציה של היצרן, את מקור האמת לסכמה.

Public API, MCP ואפליקציית האינטרנט

ממשק	שימוש	מודל תאימות
Public API	מערכות לקוח, שותפים ואוטומציה חיצונית	משאבים יציבים ועם ניהול גרסאות
MCP	אינטראקציות של כלי בינה מלאכותית מבוססות הרשאות	חוזי כלים ופלטים מובנים ותמציתיים
אפליקציית אינטרנט	תהליכי עבודה אנושיים במוצר Living Security	חוזים בבעלות האפליקציה שעשויים להתפתח יחד עם הממשק

למידע על חיבור כלי בינה מלאכותית אל Living Security, ראו אינטגרציית MCP.

קבלת עזרה

פנו לתמיכה של Living Security וצרפו:

הארגון והאזור
שם ה-SDK והגרסה, אם נעשה בו שימוש
חותמת זמן UTC, שיטה ונתיב
סטטוס HTTP וגוף השגיאה לאחר ניקוי מידע רגיש

לעולם אל תכללו סודות של מפתחות גישה, אסימוני נושא או נתוני לקוח פרטיים.

קישורים נוספים

מפתחות גישה ל-API

יצירה, רוטציה וביטול של פרטי גישה ל-API.

אינטגרציית MCP

חיבור כלי בינה מלאכותית נתמכים באמצעות Model Context Protocol.

API ציבורי

מדריך עזר ל-API ציבורי

לפני שמתחילים

מארחים אזוריים

משאבים קודמים (Legacy)

אימות

TypeScript SDK

בקשת REST ישירה

מחזור החיים של מפתח גישה

דפדוף

שגיאות

תאימות והוצאה משימוש

Public API, MCP ואפליקציית האינטרנט

קבלת עזרה

קישורים נוספים

מפתחות גישה ל-API

אינטגרציית MCP

API ציבורי

מדריך עזר ל-API ציבורי

​לפני שמתחילים

​מארחים אזוריים

​משאבים קודמים (Legacy)

​אימות

​TypeScript SDK

​בקשת REST ישירה

​מחזור החיים של מפתח גישה

​דפדוף

​שגיאות

​תאימות והוצאה משימוש

​Public API, MCP ואפליקציית האינטרנט

​קבלת עזרה

​קישורים נוספים

מפתחות גישה ל-API

אינטגרציית MCP

לפני שמתחילים

מארחים אזוריים

משאבים קודמים (Legacy)

אימות

TypeScript SDK

בקשת REST ישירה

מחזור החיים של מפתח גישה

דפדוף

שגיאות

תאימות והוצאה משימוש

Public API, MCP ואפליקציית האינטרנט

קבלת עזרה

קישורים נוספים