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

Для серверной интеграции нужны ключ доступа и JWT. Ключ доступа (credential) создаётся в Alitos и имеет вид alitos_cred_<prefix>.<secret>. Обменяйте его через /oauth/token на JWT и передавайте JWT в запросах /v1/external.

Храните ключ в хранилище секретов, JWT — только в памяти процесса. Не включайте их в клиентское приложение, репозиторий или логи. JWT для REST не подходит для MCP, и наоборот.

Создайте ключ

Пользователь должен иметь право external_api_access. В интерфейсе Alitos откройте «Доступ к Alitos API» и нажмите «Создать токен». Выберите только права и кабинеты, которые нужны интеграции. Для быстрого старта достаточно cabinet:read.

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

• имя от 1 до 255 символов;

• один или несколько scopes — разрешённых групп действий;

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

• необязательный срок expiresInDays от 1 до 365 дней. Без него ключ не истекает.

Если cabinetAllowlist не задан, ключ действует на все кабинеты, доступные владельцу в момент запроса (all_current). Пустой массив запрещён. Scopes и список кабинетов неизменяемы; для их изменения выпустите новый ключ.

Секрет показывается один раз. Alitos хранит только его SHA-256-хеш и не может восстановить полное значение. Сразу перенесите ключ в хранилище секретов. Потерянный ответ или разрыв соединения не означают отмену создания: обновите список ключей и отзовите ключ с недоступным секретом, прежде чем создавать новый. Не повторяйте выдачу автоматически.

Обменяйте ключ на JWT

Полный запрос OAuth 2.0 Token Exchange приведён в быстром старте.

В scope передавайте нужные scopes через пробел. Они должны входить в права ключа; если поле опущено, JWT получает все scopes ключа. Например, ключ только с cabinet:read нельзя обменять на JWT с cabinet:deals:write. Значение resource должно точно совпадать с https://api.alitos.io/v1/external.

JWT действует 60 минут. Refresh token не выдаётся. Получайте новый JWT повторным обменом до истечения срока; не выполняйте обмен перед каждым запросом к API.

Как проверяется доступ

JWT фиксирует пользователя и ключ: подменить их полями запроса нельзя. При каждом вызове сервер проверяет право external_api_access, подпись, срок и назначение JWT, scope операции, ограничение по кабинетам и текущие права пользователя в выбранном кабинете. Scope ограничивает действия, но не выдаёт пользователю новые права на кабинет.

Состояние самого ключа проверяется при обмене. Отзыв ключа сразу запрещает новый обмен; уже выданный JWT может действовать до истечения своих 60 минут.

Замените или отзовите ключ

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

При компрометации отзовите ключ и обратитесь к администратору для снятия права external_api_access. Один отзыв ключа не прекращает немедленно действие уже выданного JWT.

Управление ключами через API

Эти методы принимают обычный интерактивный токен пользователя Alitos — ALITOS_USER_TOKEN в примерах Bash. Внешний JWT и сам ключ alitos_cred_... для управления ключами не подходят. Если вы настраиваете интеграцию вручную, создайте ключ через интерфейс, как описано выше.

Пример создаёт ключ для быстрого старта. Замените фиктивный 123456789 идентификатором кабинета, доступного владельцу:

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

Фрагмент ответа; идентификаторы фиктивные, секрет сокращён:

{
  "id": 42,
  "idString": "42",
  "scopes": ["cabinet:read"],
  "credential": "alitos_cred_ab12cd34ef56gh78.<secret>"
}

Сохраните полное значение credential из вашего ответа. Получить список ключей можно без раскрытия секретов:

curl 'https://api.alitos.io/external-access/credentials' \
  --header "Authorization: Bearer ${ALITOS_USER_TOKEN}"

Для отзыва сохраните idString выбранного ключа в CREDENTIAL_ID:

curl --request POST \
  "https://api.alitos.io/external-access/credentials/${CREDENTIAL_ID}/revoke" \
  --header "Authorization: Bearer ${ALITOS_USER_TOKEN}" \
  --header 'Content-Type: application/json' \
  --data '{"reason":"Замена ключа интеграции"}'

idString — точный положительный Int64 в виде десятичной строки. Числовой id сохранён для совместимости; в JavaScript он безопасен только в пределах Number.MAX_SAFE_INTEGER. Старый сервер может не вернуть idString: не восстанавливайте его из числа, которое уже потеряло точность. Полные поля и ограничения — в OpenAPI.

Ошибки обмена

/oauth/token возвращает поля error и error_description формата OAuth. Ошибки запросов к кабинетам используют другой формат — Problem Details.

При 429 соблюдайте Retry-After. Повторный обмен не исправляет недостаточные права или неверное значение resource.