> ## 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.

# Legacy Public API

> תחזוקה של אינטגרציות קיימות מסוג /api/v1 המחליפות מפתח גישה ל-API באסימון נושא (bearer token).

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

לאינטגרציה חדשה, התחילו ב[מדריך התחלה מהירה ל-API](/he/developers/v1/quickstart) וב[אימות](/he/developers/v1/authentication). ה-API החדש של `/v1` משתמש במפתחות API של חשבון שירות (service account) או באסימוני גישה של OAuth.

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

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

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

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

<Note>
  תיבת הדו-שיח Access Keys מציגה את הסוד החד-פעמי, אך אינה מציגה את מזהה
  המנפיק של ה-API. אם Living Security לא סיפקה לכם את מזהה המנפיק יחד עם פרטי
  הגישה ל-Public API, בקשו אותו מ[התמיכה של Living
  Security](mailto:support@livingsecurity.com). מזהה המנפיק אינו מזהה מפתח
  הגישה ואינו מזהה הארגון.
</Note>

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

החוזה הקודם (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 מתבצעת בשני שלבים:

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

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

```http theme={null}
Authorization: Bearer <access-token>
x-organization-id: <organization-id>
```

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

### TypeScript SDK

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

```bash theme={null}
npm install @livingsecurity/sdk@^1
```

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

```typescript theme={null}
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, שלחו את אסימון הנושא ואת מזהה הארגון בכל בקשה:

```bash theme={null}
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 מתועדות מופיעות בצורה הכללית הבאה:

```json theme={null}
{
  "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](/he/integrations/mcp).

## קבלת עזרה

פנו ל[תמיכה של Living Security](mailto:support@livingsecurity.com) וצרפו:

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

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

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

<CardGroup cols={2}>
  <Card title="מפתחות גישה ל-API" icon="key" href="/he/integrations/api-keys">
    יצירה, רוטציה וביטול של פרטי גישה ל-API.
  </Card>

  <Card title="אינטגרציית MCP" icon="robot" href="/he/integrations/mcp">
    חיבור כלי בינה מלאכותית נתמכים באמצעות Model Context Protocol.
  </Card>
</CardGroup>


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