Ключи доступа и авторизация

External API использует два типа токенов: долгоживущий ключ доступа и короткоживущий JWT. Resource endpoints принимают только JWT.

Ключ доступа

Ключ создается авторизованным пользователем Alitos и выглядит как alitos_cred_<prefix>.<secret>.

Секрет показывается один раз. Alitos хранит только SHA-256 hash и не может восстановить полное значение.

При создании задаются:

• имя длиной до 255 символов;

• один или несколько scopes;

• необязательный cabinetAllowlist от 1 до 100 кабинетов;

• необязательный expiresInDays от 1 до 365.

Если cabinetAllowlist не задан, ключ действует на все кабинеты, доступные владельцу в момент запроса. Пустой массив запрещен, чтобы случайно не расширить доступ.

Scopes и список кабинетов неизменяемы. Для изменения выпустите новый ключ.

Создание через API

Credential endpoints принимают обычный интерактивный токен Alitos, а не внешний JWT.

curl --request POST 'https://api.alitos.io/external-access/credentials' \
  --header "Authorization: Bearer ${ALITOS_USER_TOKEN}" \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "gck-deals-import",
    "scopes": ["cabinet:deals:write"],
    "cabinetAllowlist": ["123456789"]
  }'

{
  "id": 42,
  "name": "gck-deals-import",
  "prefix": "alitos_cred_ab12cd34ef56gh78",
  "resource": "https://api.alitos.io/v1/external",
  "scopes": ["cabinet:deals:write"],
  "cabinetAllowlist": ["123456789"],
  "createdAt": "2026-08-09T12:00:00Z",
  "expiresAt": null,
  "credential": "alitos_cred_ab12cd34ef56gh78.0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
}

Все значения в примере фиктивные. Немедленно перенесите полное значение credential в secret manager.

Обмен на JWT

Используйте OAuth 2.0 Token Exchange. Полный запрос показан в быстром старте.

Запрошенный scope должен быть подмножеством scopes ключа. Если scope не передан, JWT получает все scopes ключа.

Значение resource должно точно совпадать с https://api.alitos.io/v1/external.

JWT действует 60 минут. Refresh token не выдается. Кэшируйте JWT только в памяти процесса и выполняйте новый exchange до истечения срока.

Проверка доступа

Идентичность пользователя и ключа зафиксирована в JWT. Ее нельзя заменить полем запроса.

При каждом вызове Alitos повторно проверяет:

• глобальное право external_api_access;

• состояние ключа и JWT;

• scope операции;

• ограничение по кабинету;

• актуальные права пользователя в кабинете.

JWT для REST нельзя использовать в MCP, и наоборот.

Ротация и отзыв

Плановая ротация не требуется, если ее не требует политика компании. Выпустите новый ключ при смене владельца, набора scopes или списка кабинетов.

curl --request POST \
  'https://api.alitos.io/external-access/credentials/42/revoke' \
  --header "Authorization: Bearer ${ALITOS_USER_TOKEN}" \
  --header 'Content-Type: application/json' \
  --data '{"reason":"Credential owner changed"}'

Отзыв сразу запрещает новый token exchange. Уже выпущенный JWT может действовать еще до 60 минут.

При компрометации отзовите ключ и обратитесь к администратору для снятия права external_api_access.

Ошибки OAuth

/oauth/token возвращает стандартные поля error и error_description, а не RFC 7807.