> ## 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-ключа с ограниченным набором областей доступа. Чтобы выбрать
один из двух методов и понять, как используются сервисные учетные записи, см. раздел [Аутентификация](/ru/developers/v1/authentication).

<Note>
  Доступ к OAuth должен быть включен для вашей организации. В ходе настройки вы получите
  региональную конечную точку токенов, издателя (issuer), аудиторию (audience) и метод аутентификации клиента.
  Если вам нужны эти параметры или у вас нет доступа к управлению клиентами, обратитесь
  в службу поддержки Living Security.
</Note>

Предоставление учетных данных клиента (client credentials grant) представляет вашу сервисную учетную запись. Оно не выполняет вход пользователя
и не предлагает клиенту авторизовать приложение. Делегированная авторизация через
браузер — это отдельная возможность OAuth, и данные операции ее не предоставляют.

## Перед началом работы

* Создайте [сервисную учетную запись](/ru/developers/developer-hub/service-accounts), имеющую только те
  разрешения, которые нужны интеграции.
* Используйте учетные данные управления с `service_account:manage` и каждым разрешением,
  которое вы хотите предоставить новому клиенту. Целевая учетная запись также должна иметь эти
  разрешения. Клиент не может расширить полномочия ни одной из учетных записей.
* Выберите [регион](/ru/developers/v1/regions) организации. Учетные данные API и
  токены доступа OAuth должны использоваться на соответствующем региональном хосте API.
* Храните секрет клиента и токены в серверном хранилище секретов. Никогда не размещайте
  их в коде браузера, мобильных приложениях, системе управления версиями или журналах запросов.

## Создание клиента

`POST /v1/oauth_clients` требует `service_account_id`, непустой список явно указанных
`scopes` и `Idempotency-Key`. Подстановочные знаки не допускаются. Клиент поддерживает
до 100 областей доступа при суммарной длине не более 4 096 символов. Каждая сервисная
учетная запись может иметь не более 20 клиентов или незавершенных операций создания/очистки.
Отзыв немедленно блокирует доступ к API. Клиент или неопределенное
создание на стороне провайдера продолжают учитываться в лимите, пока не будет подтверждена удаленная очистка.
Брошенное резервирование или создание, в отношении которого доказано, что оно завершилось сбоем до начала работы
провайдера, может безопасно освободить свой слот. Его ключ повторной отправки по-прежнему относится к исходной
попытке; прежде чем решать, создавать ли замену, восстановите подтверждение (receipt) этой попытки.

Выберите один ключ повторной отправки для этой попытки создания и сохраните его **до** отправки
запроса. Используйте от 1 до 255 видимых символов ASCII без пробелов. Используйте его повторно с той же
учетной записью, теми же областями доступа, тем же субъектом управления, регионом и версией API после потери
ответа. Ротация учетных данных управления в рамках той же сервисной учетной записи
не создает новую идентичность повторной отправки.

Установите пакет Python `requests`. Загрузите следующие значения среды с помощью
вашей обычной системы управления секретами и конфигурацией:

| Переменная | Значение |
| - | - |
| `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` | Устраните проблемы с доступом к учетным данным, разрешениям или правам (entitlement) перед повторной попыткой. |
| `404` | Проверьте включение OAuth, региональный хост и принадлежность ресурса. |

Информацию об идентификаторах запросов и восстановлении см. в разделе [ошибки](/ru/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.