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

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

Сессионная аутентификация (кабинет)

Помимо Bearer-токенов, приватные маршруты /v1 принимают сессионную аутентификацию на базе Laravel Sanctum — её использует веб-кабинет (SPA) через cookie. Для server-to-server интеграций она не предназначена: используйте API-токены (описаны ниже).

Сессионный вход состоит из четырёх шагов:

1. Фронтенд запрашивает CSRF-cookie: GET /sanctum/csrf-cookie.
2. Логин: POST /v1/auth/login с полями email и password.
3. Сервер создаёт сессионную cookie.
4. Каждый следующий запрос идёт с этой cookie и CSRF-токеном в заголовке.

Вход по логину и паролю (per-user токен)

Штатный способ выпустить токен — API-токены сервисного аккаунта (см. ниже): один токен на всю интеграцию. Если же нужен отдельный токен на каждого конечного пользователя — например, мобильное или партнёрское приложение, где каждый сотрудник входит своими email и паролем, — используйте POST /v1/auth/mobile/login. Это единственный публичный эндпоинт, который обменивает учётные данные пользователя на Bearer-токен.

Тело запроса:

{
  "data": {
    "message": "Logged in.",
    "email_verified": true,
    "token": "456|aisar_xxx_EXAMPLE"
  }
}

• Имя токена — mobile:{device_name}. Повторный вход с тем же device_name отзывает прежний одноимённый токен, поэтому на каждом устройстве живёт ровно один токен.
• Токен получает полный доступ в рамках роли пользователя (Sanctum-абилки ["*", "broadcasting:connect"]); абилка broadcasting:connect нужна, чтобы авторизовать realtime-подписки на WebSocket.
• В отличие от API-токенов сервисного аккаунта (у которых нет срока действия), этот токен имеет скользящий срок (по умолчанию 90 дней), который продлевается при активном использовании.

Если email пользователя ещё не подтверждён, токен всё равно возвращается, но с email_verified: false. Завершите подтверждение вызовом POST /v1/auth/email/verify-code с этим Bearer-токеном и 6-значным кодом, отправленным пользователю на почту (повторная отправка кода — POST /v1/auth/email/resend-code):

{
  "code": "123456"
}

Ошибки: 422 с ошибкой на поле email — неверные учётные данные, попытка входа сервисным API-аккаунтом или отсутствие доступа к приложению AISAR. 429 — сработал лимит входа: не более 5 попыток за 15 минут на пару email + IP.

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

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

Authorization: Bearer 123|xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

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

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

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

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

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

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

Права токена

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

Роли и права (RBAC)

Внутри компании доступ определяется ролью пользователя. В AISAR три роли: admin, manager и agent — каждая даёт свой набор прав, которые отдельные эндпоинты проверяют индивидуально (см. «Права токена» выше и справочник REST).

Права привязаны к компании (мультиарендность): один и тот же пользователь может иметь разные роли в разных компаниях, а каждый запрос выполняется в контексте той компании, к которой привязан токен.

Ответ GET /v1/me включает поле permissions — плоский массив строк со всеми правами пользователя в текущей компании. Каждый ключ имеет вид {ресурс}.{действие}, например conversation.create, conversation.view, message.create, contact.create, deal.create, template.view, channel.view, broadcast.create, api_token.create. Это те же права, что серверные эндпоинты проверяют на каждый запрос; фронтенд гейтит элементы интерфейса (кнопки, действия) по наличию нужного ключа в этом массиве.

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

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

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

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

{
  "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) перед повтором, желательно с экспоненциальной задержкой при повторных превышениях.

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