Разделы документации

Admin API: API-токены

Три метода Admin API для работы с токенами: получить список, создать токен с нужным доступом и сроком, отозвать токен по ID.

Через API доступны те же действия, что и во вкладке панели Настройки → API: посмотреть список токенов, создать токен и отозвать его. Работа с токенами в панели описана на странице API-токены. Все три метода требуют токен с доступом Полный доступ (full). Авторизация описана на странице Admin API: обзор и авторизация, формат ответов и ошибок — на странице Формат запросов, ответов и ошибок.

Объект токена

Список и ответ на создание возвращают токен в одном виде:

Поле	Тип	Описание
`id`	строка, UUID	ID токена. Подставляется в адрес при отзыве
`name`	строка	Название
`prefix`	строка	Первые 12 символов токена и многоточие, например `trk_01234567…`
`scopes`	массив строк	Вид доступа, одно значение: `reports:read`, `spend:write` или `full`. Что разрешает каждый — в разделе Виды доступа
`expires_at`	строка, дата RFC 3339	Окончание срока действия. У токена без срока поля нет
`last_used_at`	строка, дата RFC 3339	Время последнего запроса с этим токеном. Пока токеном не пользовались, поля нет
`created_at`	строка, дата RFC 3339	Время создания
`created_by`	строка, UUID	ID пользователя, который создал токен. От его имени выполняются запросы
`created_by_email`	строка	Email этого пользователя

Значение самого токена в объект не входит. Оно приходит один раз — в ответе на создание.

Методы

Список токенов

http

GET /api/v1/api-tokens

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

Права токена: full. Параметров пути, запроса и тела нет. Постраничности и фильтров нет.

Ответ — код 200 и массив объектов токена. Новые идут первыми. Если токенов нет, приходит пустой массив [].

Истёкший токен остаётся в списке, пока его не отзовут. Отличить его можно по expires_at: дата в прошлом.

Пример запроса:

bash

curl https://panel.example.com/api/v1/api-tokens \
  -H "Api-Key: <токен>"

Пример ответа:

json

[
  {
    "scopes": ["reports:read"],
    "expires_at": "2027-01-02T10:15:00Z",
    "id": "3f2b8c1e-5a47-4d1b-9c0e-7a6d2f4b8e10",
    "name": "BI-отчёты",
    "prefix": "trk_01234567…",
    "last_used_at": "2026-10-04T08:41:12.305118Z",
    "created_at": "2026-10-04T10:15:00.114207Z",
    "created_by": "9d1e4c70-2b3a-4f5d-8e6c-0a1b2c3d4e5f",
    "created_by_email": "[email protected]"
  }
]

Создать токен

http

POST /api/v1/api-tokens

Создаёт токен и один раз возвращает его значение.

Права токена: full. Новый токен принадлежит тому же пользователю, что и токен, которым отправлен запрос.

Поле	Тип	Обязательность	Описание
`name`	строка	да	Название. До 200 байт: это 200 латинских символов или 100 кириллических. Пробелы по краям отбрасываются
`scopes`	массив строк	нет	Вид доступа, ровно одно значение: `reports:read`, `spend:write` или `full`. Без поля — `reports:read`. Значение `spend:write` принимается только на платной лицензии
`expires_at`	строка, дата RFC 3339	нет	Окончание срока действия. Дата в будущем и не дальше 365 суток от момента запроса. Без поля — 90 суток

Одинаковые названия допускаются. Изменить название, доступ или срок готового токена нельзя: отзовите токен и создайте новый.

Ответ — код 201:

Поле	Тип	Описание
`token`	строка	Значение токена: `trk_` и 40 символов из цифр и букв от `a` до `f`
`item`	объект	Объект токена без `last_used_at`

Поле token приходит только в этом ответе. Сохраните его сразу: получить значение повторно нельзя ни через API, ни в панели.

Ошибки:

Код	`code`	`message`	Когда
`422`	`validation`	`name is required`	Поля `name` нет, оно пустое или состоит из пробелов. Тот же ответ приходит, если тело не разобрано: невалидный JSON, поле не того типа или дата не в формате RFC 3339
`422`	`validation`	`name is too long`	Название длиннее 200 байт
`422`	`validation`	`choose exactly one scope: reports:read, spend:write or full`	В `scopes` пустой массив, больше одного значения или неизвестное значение
`422`	`validation`	`expires_at must be in the next 365 days`	Дата в прошлом или дальше 365 суток
`403`	`spend_paid_required`	`Расширение для расходов доступно после оплаты лицензии.`	Запрошен `spend:write` на пробной лицензии

Пример запроса:

bash

curl -X POST https://panel.example.com/api/v1/api-tokens \
  -H "Api-Key: <токен>" \
  -H "Content-Type: application/json" \
  -d '{"name":"BI-отчёты","scopes":["reports:read"],"expires_at":"2027-01-02T10:15:00Z"}'

Пример ответа:

json

{
  "token": "trk_0123456789abcdef0123456789abcdef01234567",
  "item": {
    "scopes": ["reports:read"],
    "expires_at": "2027-01-02T10:15:00Z",
    "id": "3f2b8c1e-5a47-4d1b-9c0e-7a6d2f4b8e10",
    "name": "BI-отчёты",
    "prefix": "trk_01234567…",
    "created_at": "2026-10-04T10:15:00.114207Z",
    "created_by": "9d1e4c70-2b3a-4f5d-8e6c-0a1b2c3d4e5f",
    "created_by_email": "[email protected]"
  }
}

Отозвать токен

http

DELETE /api/v1/api-tokens/{id}

Удаляет токен. Запросы с ним сразу начинают получать 401.

Права токена: full. Тела запроса нет.

Параметр	Где	Тип	Обязательность	Описание
`id`	путь	строка, UUID	да	Значение `id` из списка токенов или из ответа на создание

Ответ — код 204 без тела.

Ошибки:

Код	`code`	`message`	Когда
`404`	`not_found`	`resource not found`	Токена с таким ID нет: ID указан с ошибкой или токен уже отозван
`400`	`bad_request`	`некорректный идентификатор или значение`	`id` не в формате UUID

Пример запроса:

bash

curl -X DELETE https://panel.example.com/api/v1/api-tokens/3f2b8c1e-5a47-4d1b-9c0e-7a6d2f4b8e10 \
  -H "Api-Key: <токен>"

Ограничения

Отозвать можно любой токен команды, в том числе тот, которым отправлен запрос. После этого следующий запрос с ним получит 401.
Восстановить отозванный токен нельзя. Повторный запрос с тем же ID отвечает 404.
Метода для изменения или продления токена нет. Чтобы сменить токен в интеграции, создайте новый, подставьте его и отзовите старый.
Токены пользователя удаляются вместе с ним, а также когда его роль становится ниже администратора — см. От чьего имени работает токен.
При неактивной лицензии все три метода отвечают 402 — см. Истёкшая лицензия.

Обновлено 4 октября 2026Нужна помощь? ↗