Перейти к содержимому
AISARAISAR
REST API

API-токены

Управление сервисными API-токенами — bearer-токенами для server-to-server интеграций (тот же способ авторизации, что и у примеров в этом справочнике). Группа позволяет создать токен, прочитать его метаданные, обновить название/описание и удалить токен.

Создание и хранение токена

Создание токена заводит скрытый сервисный аккаунт с ролью admin в текущей компании; значение токена показывается только один раз, в ответе на создание. Удаление токена удаляет и сам сервисный аккаунт.

Создать или переименовать токен может только администратор компании — человек, вошедший через сессию кабинета, либо сотрудник платформы; менеджер и агент получают обычный 403. Вызвать POST/PATCH от имени самого API-токена нельзя ни при каких правах, в том числе тем же сервисным аккаунтом, который этот токен представляет, — такой запрос всегда отклоняется с 403 и error: "api_token_admin_only". Список токенов, получение по id и удаление этим ограничением не связаны — их можно вызывать и с самого API-токена, если у него есть право api_token.view / api_token.delete.

Удаление токена — способ отключить интеграцию, которая работает от имени компании, в том числе интеграцию партнёра, подключившего вашу компанию: все вызовы с удалённым токеном сразу получают 401. Вместе с токеном отзываются и временные embed-токены (POST /v1/embed/auth, живут 8 часов), которые он успел выпустить, — иначе интеграция могла бы продолжать работать через них ещё некоторое время после удаления. Понизить или отозвать сервисный аккаунт через управление участниками (/v1/companies/current/members/{memberId}/role, .../revoke) нельзя — такие вызовы отвечают 404. Восстановить удалённый токен невозможно: чтобы вернуть интеграцию, выпустите новый токен и передайте его интегратору. Выпуск, переименование и удаление токена фиксируются в журнале аудита платформы.

Чтение токена

При чтении токена (список или получение по id) поле token уже не возвращается — доступны только метаданные (name, description, created_at, last_used_at).

Какой токен нужен для вызова

С 2026-09-28 все эндпоинты группы требуют полного токена — сессии пользователя или API-токена со всеми правами. Узкий токен с ограниченным набором прав (например, токен встроенного окна CRM) получает 403 с error: "full_token_required": так короткоживущий токен не может выпустить себе постоянный.

Тело запроса

В теле запроса на создание и обновление:

  • name — обязательное, строка до 255 символов.
  • description — необязательное, строка до 1000 символов, допускает null.

Эндпоинты

МетодПуть
GET/v1/api-tokens

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

POST/v1/api-tokens

Создание API-токена

GET/v1/api-tokens/{id}

Получение API-токена

PUT/v1/api-tokens/{id}

Обновление названия/описания токена

PATCH/v1/api-tokens/{id}

Частичное обновление названия/описания токена

DELETE/v1/api-tokens/{id}

Удаление API-токена (и сервисного аккаунта)

Примеры

Создание API-токена

Запрос

bash
curl -X POST https://api.aisar.app/v1/api-tokens \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "n8n Integration",
    "description": "Server-to-server token for the n8n automation"
  }'

Ответ

json
{
  "data": {
    "id": 42,
    "name": "n8n Integration",
    "description": "Server-to-server token for the n8n automation",
    "created_at": "2026-03-15T10:00:00.000000Z",
    "token": "42|aBcDeFgHiJkLmNoPqRsTuVwXyZ0123456789abcdefg"
  }
}

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

Запрос

bash
curl https://api.aisar.app/v1/api-tokens \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Ответ

json
{
  "data": [
    {
      "id": 42,
      "name": "n8n Integration",
      "description": "Server-to-server token for the n8n automation",
      "created_at": "2026-03-15T10:00:00.000000Z",
      "last_used_at": "2026-03-16T08:12:44.000000Z"
    }
  ]
}

Получение токена по id

Запрос

bash
curl https://api.aisar.app/v1/api-tokens/42 \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Ответ

json
{
  "data": {
    "id": 42,
    "name": "n8n Integration",
    "description": "Server-to-server token for the n8n automation",
    "created_at": "2026-03-15T10:00:00.000000Z",
    "last_used_at": "2026-03-16T08:12:44.000000Z"
  }
}

Обновление названия и описания

Запрос

bash
curl -X PUT https://api.aisar.app/v1/api-tokens/42 \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "n8n Integration (prod)",
    "description": "Rotated server-to-server token for the n8n automation"
  }'

Ответ

json
{
  "data": {
    "id": 42,
    "name": "n8n Integration (prod)",
    "description": "Rotated server-to-server token for the n8n automation",
    "created_at": "2026-03-15T10:00:00.000000Z",
    "last_used_at": "2026-03-16T08:12:44.000000Z"
  }
}

Удаление токена

Запрос

bash
curl -X DELETE https://api.aisar.app/v1/api-tokens/42 \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Ответ

json
{
  "data": {
    "message": "API token deleted."
  }
}