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

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-токеном в заголовке.

Лимиты входа и блокировка аккаунта

POST /v1/auth/login принимает не более 10 попыток за 15 минут на пару email + IP и не более 100 запросов в минуту с одного IP. Поверх этого действует блокировка на уровне аккаунта: после 20 неудачных попыток входа на один email за 15 минут (с любых IP) вход в этот аккаунт отклоняется до истечения окна даже с верным паролем, а владельцу аккаунта уходит письмо-предупреждение (не чаще одного раза за окно). Счётчик неудач ведётся и для незарегистрированных адресов, поэтому ответ не выдаёт, существует ли аккаунт.

Блокировка общая для POST /v1/auth/login и POST /v1/auth/mobile/login: оба эндпоинта проверяют одни и те же учётные данные. Успешный вход обнуляет счётчик неудач, завершённый сброс пароля снимает блокировку сразу. И лимиты, и блокировка отвечают 429 с заголовком Retry-After:

{
  "data": {
    "message": "Too many attempts. Please try again later.",
    "error": "too_many_attempts",
    "retry_after": 840
  }
}

Вход по логину и паролю (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 дней), который продлевается при активном использовании.
• Сброс пароля пользователя (POST /v1/auth/reset-password) отзывает все его персональные токены, не только mobile:*, и завершает его веб-сессии: после сброса нужен новый вход. API-токены сервисного аккаунта это не затрагивает — они принадлежат сервисному аккаунту, а не пользователю.

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

{
  "code": "123456"
}

POST /v1/auth/email/verify-code принимает не более 10 запросов за 10 минут на пользователя. На каждый код даётся 5 неверных попыток: пятая неверная попытка сжигает код, и ответ — 422 с error: "verification_code_exhausted" (плюс ошибка на поле code). После этого нужен новый код через POST /v1/auth/email/resend-code. Неверный, истёкший или уже использованный код до исчерпания попыток — 422 с ошибкой на поле code без поля error.

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

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

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

Authorization: Bearer 123|xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

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

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

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

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

Создание токена в ответ возвращает поле 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/мин.

Такие узкие лимиты (с 2026-09-26 это касается любого JSON-ответа 429 на платформе) возвращают заголовки Retry-After, X-RateLimit-Reset, X-RateLimit-Limit и X-RateLimit-Remaining, но тело у них короче: {"data": {"message": "Too Many Attempts."}} без retry_after — ориентируйтесь на Retry-After. Публичные эндпоинты чат-виджета сайта (их вызывает сам сниппет, не Bearer-токен) тоже ограничены: создание сессии посетителя — 10 в минуту и 30 в час на пару «канал + IP посетителя» и 600 в час на канал; отправка сообщений и загрузка файлов — 30 в минуту на пару «канал + IP».

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

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

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