AISARAISAR

Аутентификация

Bearer-токены, управление ими и лимиты частоты запросов.

AISAR API использует Bearer-токены на базе Laravel Sanctum (personal access tokens). Каждый токен привязан к отдельному сервисному аккаунту, а сервисный аккаунт — к одной компании: все запросы с токеном выполняются в контексте этой компании.

Заголовок запроса

Передавайте токен в заголовке Authorization на каждом запросе:

text
Authorization: Bearer 123|xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Формат токена — {id}|{plaintext} (стандартный формат Sanctum). Передавайте его целиком, включая часть до |.

Создание и отзыв токена

Токен создаётся в кабинете компании: Настройки → Системы → API. Требуется тариф Business (фича api) и право api-token.create. При создании AISAR заводит новый сервисный аккаунт (отдельный User с флагом сервисного аккаунта) и выпускает для него токен — он показывается только один раз в момент создания.

Та же страница управляет токенами через REST-эндпоинты (можно вызывать их и напрямую, из-под уже существующего токена/сессии):

Метод и путьНазначение
GET /v1/api-tokensСписок токенов компании
POST /v1/api-tokensСоздать токен (name, description)
GET /v1/api-tokens/{id}Данные одного токена
PATCH /v1/api-tokens/{id}Переименовать / изменить описание
DELETE /v1/api-tokens/{id}Отозвать токен безвозвратно

Создание токена в ответ возвращает поле token с полным значением Bearer-токена — оно приходит только в этом ответе и больше нигде не показывается. Отзыв (DELETE) удаляет сервисный аккаунт вместе со всеми его токенами — действие необратимо.

Токены не имеют срока действия по умолчанию — они остаются рабочими, пока их явно не отзовут.

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

Права токена

Сервисный аккаунт создаётся с ролью «Администратор» в компании, поэтому токен по умолчанию имеет полный доступ к рабочей области. Конкретные эндпоинты дополнительно проверяют разрешения (например, conversation.create для отправки сообщений, conversation.view для загрузки файлов, template.view для чтения шаблонов) — они описаны в справочнике REST и в сценарии отправки сообщений.

Лимиты частоты запросов

Каждый Bearer-токен ограничен 3000 запросами за 60 секунд. Лимит считается индивидуально по токену — активность одного токена не влияет на лимит других.

Каждый ответ (кроме запросов без Bearer-токена) содержит заголовки:

ЗаголовокЗначение
X-RateLimit-LimitЛимит окна — 3000
X-RateLimit-RemainingСколько запросов осталось в текущем окне

При превышении лимита сервер возвращает 429 с телом и дополнительным заголовком Retry-After (секунды до сброса):

Ответ 429
{
  "message": "Too Many Requests.",
  "retry_after": 42
}

Некоторые группы эндпоинтов (например, тяжёлые операции с рассылками и AI-агентами) имеют дополнительный, более узкий лимит — в таком случае 429 может прийти раньше общего лимита в 3000/мин.

Обработка 401 и 429

  • 401 Unauthorized — токен отсутствует, невалиден или отозван. Тело: {"message": "Unauthenticated."}. Проверьте заголовок Authorization и что токен не был отозван в кабинете.
  • 429 Too Many Requests — превышен лимит. Дождитесь retry_after секунд (или значения заголовка Retry-After) перед повтором, желательно с экспоненциальной задержкой при повторных превышениях.

Полная таблица статусов и формат ошибок — в разделе «Ошибки».