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

# פרטי הזיהוי של לקוח OAuth

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

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

<Note>
  יש להפעיל גישת OAuth עבור הארגון שלכם. תהליך ההגדרה שלכם מספק את נקודת הקצה האזורית של האסימונים, את המנפיק (issuer), את קהל היעד (audience) ואת שיטת האימות של הלקוח.
  אם אתם זקוקים להגדרות אלה או שאין לכם גישה לניהול לקוחות, פנו
  לתמיכה של Living Security.
</Note>

מענק פרטי הזיהוי של הלקוח (client credentials grant) מייצג את חשבון השירות שלכם. הוא אינו מחבר אדם למערכת
ואינו מבקש מלקוח לאשר יישום. הרשאה מואצלת באמצעות
דפדפן היא יכולת OAuth נפרדת ואינה מוצעת בפעולות אלה.

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

* צרו [חשבון שירות](/he/developers/developer-hub/service-accounts) עם ההרשאות הנדרשות לאינטגרציה בלבד.
* השתמשו בפרטי זיהוי לניהול עם `service_account:manage` ועם כל הרשאה
  שברצונכם להעניק ללקוח החדש. גם חשבון היעד חייב להחזיק באותן הרשאות. לקוח אינו יכול להרחיב את סמכויותיו של אף אחד מהחשבונות.
* בחרו את [האזור](/he/developers/v1/regions) של הארגון. פרטי זיהוי של API ואסימוני גישה של OAuth שייכים למארח ה-API האזורי התואם.
* שמרו את סוד הלקוח ואת האסימונים באחסון הסודות בצד השרת שלכם. לעולם אל תכניסו
  אותם לקוד דפדפן, ליישומי נייד, לבקרת גרסאות או ליומני בקשות.

## יצירת לקוח

`POST /v1/oauth_clients` דורש `service_account_id`, רשימה לא ריקה של
`scopes` מפורשים, ו-`Idempotency-Key`. תווים כלליים (wildcards) אינם מתקבלים. לקוח תומך
בעד 100 היקפים (scopes), באורך כולל של עד 4,096 תווים. לכל חשבון שירות
יכולים להיות לכל היותר 20 לקוחות או פעולות יצירה/ניקוי שטרם נפתרו.
ביטול גישה שולל באופן מיידי את הגישה ל-API. לקוח או יצירה לא ודאית אצל הספק
ממשיכים להיספר במסגרת המגבלה עד שהניקוי מרחוק יאושר.
הזמנה שננטשה או יצירה שהוכח כי נכשלה לפני תחילת העבודה אצל הספק
יכולות לשחרר את המקום שלהן בבטחה. מפתח הניסיון החוזר שלהן עדיין שייך לניסיון המקורי;
שחזרו את אישור הקבלה שלו לפני שתחליטו אם ליצור לקוח חלופי.

בחרו מפתח ניסיון חוזר אחד לניסיון יצירה זה ושמרו אותו **לפני** שליחת
הבקשה. השתמשו ב-1 עד 255 תווי ASCII גלויים, ללא רווחים. השתמשו בו שוב עם
אותו חשבון, אותם היקפים, אותו גורם ניהול, אותו אזור ואותה גרסת API לאחר אובדן
תגובה. החלפת פרטי הזיהוי לניהול תחת אותו חשבון שירות
אינה יוצרת זהות ניסיון חוזר חדשה.

התקינו את חבילת `requests` של Python. טענו את ערכי הסביבה הבאים באמצעות
ניהול הסודות וההגדרות הרגיל שלכם:

| משתנה | ערך |
| - | - |
| `LIVING_SECURITY_API_KEY` | מפתח API לניהול |
| `LIVING_SECURITY_REGION` | `us` או `eu` |
| `LIVING_SECURITY_SERVICE_ACCOUNT_ID` | מזהה חשבון שירות היעד |
| `LIVING_SECURITY_OAUTH_CREATE_KEY` | מפתח ניסיון חוזר ששמרתם קודם לכן |

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

HOSTS = {
    "us": "https://api.us-east-1.livingsecurity.ai/v1",
    "eu": "https://api.eu-west-1.livingsecurity.ai/v1",
}
base = HOSTS[os.environ["LIVING_SECURITY_REGION"]]
response = requests.post(
    f"{base}/oauth_clients",
    auth=("apikey", os.environ["LIVING_SECURITY_API_KEY"]),
    headers={
        "Living-Security-Version": "2026-07-01",
        "Idempotency-Key": os.environ["LIVING_SECURITY_OAUTH_CREATE_KEY"],
    },
    json={
        "service_account_id": os.environ["LIVING_SECURITY_SERVICE_ACCOUNT_ID"],
        "scopes": ["organization:read"],
    },
    timeout=(5, 30),
    allow_redirects=False,
)
try:
    if response.status_code != 201:
        raise RuntimeError(
            f"Client creation needs review: HTTP {response.status_code}; "
            f"request_id={response.headers.get('Request-Id', 'unknown')}"
        )
    client = response.json()
    if client.get("object") != "oauth_client" or not client.get("id"):
        raise RuntimeError("Unexpected client receipt; preserve the retry key")
    if client.get("status") != "active" or not client.get("client_secret"):
        raise RuntimeError(
            f"Client {client['id']} needs recovery; no usable secret was returned"
        )
    # Persist client['id'], client['client_id'], and client['client_secret']
    # directly in your secret manager before using the client. Do not print them.
finally:
    response.close()
```

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

תגובות היצירה ואישור הקבלה משתמשות ב-`201` וכוללות משאב `oauth_client`
עם `id`, `service_account_id`, `client_id`, `scopes`, `status`, `created_at` ו-
`client_secret`. התגובות מסומנות ב-`Cache-Control: no-store`.

* **`id`** מזהה את משאב הפלטפורמה. שמרו אותו לצורך אחזור וביטול גישה.
* **`client_id`** מזהה את הלקוח במהלך החלפת האסימונים. הוא אינו מזהה משאב הפלטפורמה. הוא יכול להיות `null` בזמן שהיצירה בהמתנה.
* **`client_secret`** מוחזר רק לבקשה שמשלימה את היצירה.
  כל בקשת יצירה חוזרת מחזירה `null`, כולל ניסיון חוזר לאחר אובדן תגובת הצלחה. אחזור לעולם אינו מחזיר סוד.

## התאוששות מתגובה שאבדה או שהופסקה

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

| תוצאה | הפעולה הבאה |
| - | - |
| `active`, הסוד קיים | שמרו את הסוד באופן מאובטח והמשיכו בתהליך ההטמעה. |
| `active`, הסוד חסר | לא ניתן לשחזר את הסוד. בטלו את הגישה של לקוח זה, ודאו שהביטול הושלם, ואז צרו לקוח חלופי באמצעות מפתח ניסיון חוזר חדש. |
| `pending` | היצירה לא אושרה. שמרו על אותו מפתח ניסיון חוזר. אחזרו את המשאב כדי לבדוק את מצבו; אל תיצרו כפילויות כדי לעקוף את אי-הוודאות. |
| `revoked`, `disabled` או `expired` | אל תשתמשו בלקוח זה. ודאו את תצורת החשבון המיועדת לפני הקצאת לקוח חלופי. |
| `409 idempotency_key_reuse` | הבקשה השתנתה תחת מפתח קיים. שחזרו את הפעולה המקורית לפני שתחליטו אם נדרשת יצירה נפרדת. |
| `409 invalid_request` | בדקו את מצב חשבון היעד ואת ההרשאות שהוענקו לו. אם הגעתם למגבלת הלקוחות שלו, השלימו את הניקוי לפני ניסיון חוזר; החלפת מפתח הניסיון החוזר אינה פוטרת מקום. |
| `429` | כבדו את `Retry-After`; שמרו על אותו מפתח ואותה בקשה. |
| `500`, `503` או פסק זמן ברשת | ייתכן שהתוצאה אינה ידועה. שמרו את המפתח ואת הקלטים; שחזרו את אישור הקבלה לפני שתיצרו לקוח נוסף. |
| `401` או `403` | פתרו את בעיית הגישה לפרטי הזיהוי, להרשאות או לזכאות לפני ניסיון חוזר. |
| `404` | ודאו את הפעלת OAuth, את המארח האזורי ואת הבעלות על המשאב. |

ראו [שגיאות](/he/developers/v1/errors/overview) לקבלת מזהי בקשות ופרטי התאוששות.
לעולם אל תשלחו סוד לקוח או אסימון גישה בבקשת תמיכה.

## בדיקה וביטול גישה

השתמשו בפרטי הזיהוי לניהול שלכם ובמשאב הפלטפורמה `id`:

| פעולה | בקשה | הצלחה |
| - | - | - |
| בדיקת המצב הנוכחי | `GET /v1/oauth_clients/{id}` | `200`, משאב לקוח ללא סוד |
| ביטול גישה | `DELETE /v1/oauth_clients/{id}` | `200`, משאב לקוח מבוטל ללא סוד |

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

## החלפה ללא אובדן גישה

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

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


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