Авторизация внешних интеграций¶

Назначение¶

Этот документ описывает, как работает machine-to-machine авторизация для внешних интеграций.

Один integration client может работать с одной или несколькими организациями, если такой доступ разрешен на стороне сервера.

Термины¶

integration client: серверная запись с clientId и clientSecret
доступ к организации: allowlist-запись, которая разрешает конкретному integration client работать с конкретной организацией
technical user: внутренний технический пользователь, которого система создает для конкретной пары организация + integration client
X-Organization-Id: HTTP-заголовок, через который выбирается контекст организации для org-scoped запросов

Общая схема работы¶

Внешней системе выдаются clientId и clientSecret.
Внешняя система получает access token через POST /api/account/token.
Внешняя система вызывает API с заголовком Authorization: Bearer <access_token>.
Для методов, работающих в контексте организации, дополнительно передается X-Organization-Id.
Сервер проверяет, что integration client имеет доступ к указанной организации. Для всех новых организаций доступ автоматически есть.
Если доступ разрешен, сервер автоматически переключает выполнение на technical user этой организации.

Внешняя система не передает userId и не выбирает внутреннего пользователя вручную.

Получение токена¶

Запрос¶

POST /api/account/token

Content-Type: application/json

{
  "grantType": "client_credentials",
  "clientId": "your-client-id",
  "clientSecret": "your-client-secret"
}

Важно¶

Текущая реализация ожидает JSON body.

Ответ¶

{
  "accessToken": {
    "token": "<jwt>",
    "expiresIn": 3600
  },
  "refreshToken": null,
  "currentUser": null,
  "requiresTwoFactor": false,
  "twoFactorProvider": null,
  "twoFactorToken": null
}

Важно¶

refreshToken для machine-to-machine авторизации не используется
новый access token нужно получать повторным запросом с теми же clientId и clientSecret

Семантика токена¶

Выданный JWT идентифицирует integration client, а не бизнес-пользователя.

Это означает:

сам токен не привязан к одной организации
один и тот же токен можно использовать для разных организаций, если у integration client есть доступ к ним
контекст организации выбирается на каждый запрос отдельно через X-Organization-Id

Внешней системе нужно воспринимать access token как непрозрачный токен. Не нужно строить бизнес-логику на внутренних JWT claims.

`X-Organization-Id`¶

Когда заголовок обязателен¶

X-Organization-Id обязателен для любого запроса, который должен выполняться в контексте конкретной организации.

Пример:

X-Organization-Id: 12345

Что делает сервер¶

Если в запросе передан X-Organization-Id, сервер:

читает clientId из machine token
проверяет, что integration client имеет доступ к указанной организации
заменяет текущий principal на этого technical user
передает дальше в систему уже обычные внутренние userId и organizationId

За счет этого обычная бизнес-логика, валидаторы работают так, как будто запрос выполнил внутренний пользователь организации.

Что будет, если заголовок не передать¶

Для org-scoped integration endpoints запрос будет отклонен с 401 Unauthorized.

Типовые причины:

не передан X-Organization-Id
передан некорректный X-Organization-Id

Модель доступа¶

Доступ контролируется двумя серверными сущностями:

IntegrationClient: хранит clientId и clientSecret
OrganizationIntegrationClient: allowlist-запись, которая связывает integration client с конкретной организацией

Если для пары clientId + organizationId нет allowlist-записи, org-scoped запросы будут отклоняться.

Метод создания организации¶

Endpoint¶

POST /api/integrations/organizations/apply