Version: 1.4.2

Выпуск токенов через API

API-токены выпускаются не только в интерфейсе, но и запросами к инсталляции. Этот способ применяется, когда токены выдаются из вашей системы: при подключении нового потребителя, при плановой ротации ключей и при блокировке доступа по инциденту.

Маршруты управления токенами живут на том же адресе, что и потребительское API, и требуют того же заголовка Authorization. Управляют они записями таблицы API-токены (mai_api_token) – теми же, что видны в интерфейсе. Читайте подробнее в статье API-токены.

tip

Требуется API-токен с ролью Admin. Токен с ролью User к этим маршрутам не допускается: ему доступен только выпуск временного токена.

Адрес и авторизация

Название	Значение
`<адрес инсталляции>` в примерах этой статьи	`https://ai.example.com`
Маршрут выпуска токена	`https://ai.example.com/token/create`
`base_api_url` из файла AI-профиля	`https://ai.example.com/v1`

Маршруты управления токенами лежат вне /v1: подставлять к ним base_api_url из файла AI-профиля нельзя, нужен адрес инсталляции без этого хвоста.

Токен передается так же, как на потребительских маршрутах:

Authorization: Bearer <токен администратора>

Выпуск токена

POST /token/create

curl https://<адрес инсталляции>/token/create \
  -H "Authorization: Bearer <токен администратора>" \
  -H "Content-Type: application/json" \
  -d '{
        "role": "User",
        "owner": "integration@example.com"
      }'

Поля запроса

Поле	Обязательно	Описание
`role`	Да	Укажите роль выпускаемого токена. Администратор выпускает токены с ролью `User` – ключи для обращения к нексусам.
`owner`	Да	Укажите владельца токена. Значение попадает в поле Email записи токена и в журнал обращений.
`tokenPrefix`	Нет	Укажите префикс значения токена, если вам нужно различать ключи по источнику. Допустимы только строчные латинские буквы, не более десяти. Значение по умолчанию: `ain`.

Код клиента задавать не нужно: токен выпускается в той же инсталляции, что и токен администратора, и попытка указать чужой код клиента отклоняется.

Ответ

Код ответа – 201.

{
  "tokenId": "9f1c2b7e-5d3a-4c8e-9b21-7a0f4d6e8c35",
  "token": "ain-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}

Поле	Описание
`tokenId`	Идентификатор записи токена, он же поле ID токена на форме. По нему токен блокируется и отзывается.
`token`	Значение токена. Передается потребителю целиком.

Ответ, если не заполнено обязательное поле:

{"code":3,"message":"validation failed: owner is required","details":[]}

caution

Значение токена возвращается только в ответе на выпуск. Повторно получить его нельзя: ни в интерфейсе, ни через API оно больше не отдается. Сохраните значение сразу и передайте потребителю по защищенному каналу. Если значение утрачено, выпустите новый токен и отзовите прежний.

Квота и срок действия у выпущенного токена задаются в его записи. Читайте подробнее в статье API-токены.

Просмотр токенов

GET /token

curl https://<адрес инсталляции>/token \
  -H "Authorization: Bearer <токен администратора>"

Метод возвращает токены вашей инсталляции. Чтобы получить конкретные записи, передайте их идентификаторы в параметре tokenIds через запятую:

curl "https://<адрес инсталляции>/token?tokenIds=9f1c2b7e-5d3a-4c8e-9b21-7a0f4d6e8c35" \
  -H "Authorization: Bearer <токен администратора>"

Отбор по роли и по коду клиента администратору недоступен.

{
  "tokens": [
    {
      "id": "9f1c2b7e-5d3a-4c8e-9b21-7a0f4d6e8c35",
      "clientCode": "example",
      "status": "ACTIVE",
      "role": "User",
      "owner": "integration@example.com",
      "createdAt": "2026-09-22T09:14:03Z",
      "updatedAt": "2026-09-22T09:14:03Z",
      "blockedBy": 0,
      "blockReasonAdmin": "",
      "blockReasonMwadmin": ""
    }
  ]
}

Поле	Описание
`id`	Идентификатор записи токена, поле ID токена на форме.
`clientCode`	Код клиента инсталляции, в которой выпущен токен.
`status`	Состояние токена. Соответствует полю Статус на форме: `ACTIVE` – Активен, `BLOCKED` – Заблокирован, `REMOVED` – Удален.
`role`	Роль токена.
`owner`	Владелец, указанный при выпуске. Поле Email на форме.
`createdAt`	Дата и время выпуска.
`updatedAt`	Дата и время последнего изменения записи.
`blockedBy`	Источники блокировки токена – сумма значений. Возможные опции: `0` – токен не заблокирован; `1` – администратор платформы, флажок Заблокирован администратором на форме; `2` – администратор инфраструктуры, флажок Заблокирован администратором MW на форме; `4` – исчерпание квоты, флажок Заблокирован по квоте на форме. Текста причины у этой блокировки нет. Например, `3` означает, что токен заблокирован и администратором платформы, и администратором инфраструктуры. Статус `BLOCKED` сохраняется, пока установлен хотя бы один источник. Определяйте, заблокирован ли токен и кем, по этому полю.
`blockReasonAdmin`	Причина блокировки, указанная администратором платформы. Поле Причина блокировки (администратор) на форме.
`blockReasonMwadmin`	Причина блокировки, указанная администратором инфраструктуры. Поле Причина блокировки (администратор MW) на форме.

Значения токенов в ответе не передаются.

Ответ, если идентификатор передан в неверном формате:

{"code":9,"message":"validation failed: id must be a valid UUID","details":[]}

Блокировка и отзыв

PATCH /token/<tokenId>/update

curl -X PATCH https://<адрес инсталляции>/token/<tokenId>/update \
  -H "Authorization: Bearer <токен администратора>" \
  -H "Content-Type: application/json" \
  -d '{
        "status": "BLOCKED",
        "blockReason": "Компрометация ключа, заявка INC0001234"
      }'

Поля запроса

Поле	Обязательно	Описание
`status`	Да	Укажите новое состояние токена. Доступные опции: ACTIVE – вернуть токен в работу; BLOCKED – заблокировать токен, запросы по нему перестают проходить; REMOVED – отозвать токен.
`blockReason`	Да/Нет	Укажите причину блокировки. Поле обязательно, если в поле `status` передано значение `BLOCKED`.

Блокировка запросом устанавливает источник 1 – администратор платформы, причина возвращается в поле blockReasonAdmin метода GET /token. Значение ACTIVE снимает только этот источник: блокировку администратором инфраструктуры и блокировку по квоте запросом снять нельзя.

Ответ

{"status": "success"}

Ответ подтверждает, что изменение принято. Текущее состояние токена в нем не возвращается – запросите его методом GET /token.

Ответ, если причина блокировки не указана:

{"code":9,"message":"validation failed: block reason is required when admin blocks a token","details":[]}

note

Токен возвращается в состояние Активен, когда сняты все блокировки: они устанавливаются независимо друг от друга, в том числе автоматически при исчерпании квоты. Виды блокировок и порядок их снятия описаны в статье API-токены.

caution

Отзыв токена необратим. Запись со статусом REMOVED в работу не возвращается, и запросы по такому токену больше не проходят. Чтобы выдать потребителю доступ заново, выпустите новый токен.

Временный токен

POST /token/temp-token

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

curl https://<адрес инсталляции>/token/temp-token \
  -H "Authorization: Bearer <токен администратора>" \
  -H "Content-Type: application/json" \
  -d '{"username": "contractor@example.com"}'

Поле	Обязательно	Описание
`username`	Да	Укажите, кому выдается временный токен. Значение попадает в журнал обращений.

Код ответа – 201.

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresAt": "2026-09-22 09:24:03"
}

Ответ, если запрос выполнен отозванным токеном:

{"code":401,"message":"invalid token"}

Отзывать временный токен не нужно: он перестает действовать сам. Записи в таблице API-токены у него нет, поэтому изменить его методом PATCH /token/<tokenId>/update нельзя.

Коды ответов

Код	Причина	Что делать
`400`	Не заполнено обязательное поле, передано недопустимое значение роли или статуса, префикс токена не прошел проверку.	Исправьте тело запроса.
`401`	Токен не передан, не найден или отозван.	Читайте подробнее в статье Аутентификация.
`403`	Роли токена недостаточно: токен с ролью User обратился к управлению токенами, администратор пытается изменить чужой токен или выпустить токен с ролью Admin.	Выполните запрос токеном с ролью Admin своей инсталляции.
`405`	Метод запроса не поддерживается.	Сверьте метод с описанием маршрута.
`500`	Внутренняя ошибка хранилища токенов.	Повторите запрос, при повторении обратитесь в поддержку.

note

В теле ответа есть поле code. На части ответов оно совпадает с кодом HTTP, на части содержит внутренний код ошибки – например {"code":9,…} при неуспешной проверке полей. Определяйте результат запроса по коду HTTP, а не по этому полю.

Адрес и авторизация​

Выпуск токена​

Поля запроса​

Ответ​

Просмотр токенов​

Блокировка и отзыв​

Поля запроса​

Ответ​

Временный токен​

Коды ответов​

Адрес и авторизация

Выпуск токена

Поля запроса

Ответ

Просмотр токенов

Блокировка и отзыв

Поля запроса

Ответ

Временный токен

Коды ответов