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

API-ключи (рекомендуются для интеграций)

API-ключ - это персональный токен доступа, привязанный к участнику вашего аккаунта.

Создайте ключ в разделе Настройки → Плагины → API-ключи RolChat. Секрет показывается один раз; после этого видны только первые десять символов, а RolChat хранит лишь хеш SHA-256.
Формат: rcp_, за которым следуют 32 случайных байта в base64url, всего около 45 символов. Префикс позволяет узнать ключ в логах и отличить его от токена сессии.
Области доступа: выбираются из фиксированного каталога возможностей при создании ключа. Ключ никогда не может сделать больше, чем создавший его участник: при каждом вызове проверяются оба условия - возможность входит в области доступа ключа и участник по-прежнему ею обладает. Сузьте роль участника, и ключ сузится вместе с ней.
Срок действия: ключи не истекают сами по себе. Отзовите ключ на странице профиля или через DELETE /api/v1/tokens/:id; отзыв вступает в силу немедленно. Ротации на месте нет: отзовите ключ и создайте новый.
Создание и отзыв записываются в журнал аудита.

Передавайте ключ как bearer-токен - отдельного заголовка для API-ключа нет:

curl https://api.rolchat.com/api/v1/contacts?limit=20 \
  -H "Authorization: Bearer rcp_…" \
  -H "X-Account-Id: 7c1d2c6e-…"

Запросы с API-ключом плагина ограничены 300 в минуту.

JWT-сессии

Веб-приложение и мобильные SDK входят по e-mail и паролю (или через Google либо Apple) и получают пару токенов.

Токен	Срок жизни	Примечания
Access-токен	15 минут	RS256, проверяется по JWKS на `/.well-known/jwks.json`
Refresh-токен	30 дней	Меняется при каждом обновлении; повторное использование заменённого токена отзывает всю цепочку

Утверждения (claims): sub (пользователь), acc (аккаунт), rl (роль) и, для ролей на уровне сайтов, sts (разрешённые сайты).

POST /auth/login, /auth/refresh, /auth/swap-company и /auth/logout - единственные эндпоинты аутентификации, которые не должны передавать заголовок X-Account-Id, описанный ниже.

Заголовок `X-Account-Id`

Каждый аутентифицированный запрос, кроме четырёх перечисленных выше, должен указывать аккаунт, от имени которого он выполняется:

X-Account-Id: <account uuid>

Сервер проверяет, что заголовок совпадает с утверждением acc в токене (или с аккаунтом API-ключа). Отсутствие заголовка даёт 400 missing_required_header, несовпадение - 403 account_context_mismatch. Заголовок нужен для того, чтобы ошибка в клиенте или повторно использованный токен никогда не могли незаметно прочитать данные другого клиента: несовпадение отклоняется до выполнения любого запроса к данным, а каждую строку лога можно отнести к аккаунту без декодирования токена.

Пользователи нескольких компаний

Один человек может состоять в нескольких компаниях. У каждой компании свой токен (со своим утверждением acc). Чтобы переключиться:

POST /api/v1/auth/swap-company
Authorization: Bearer <current access token>

{ "account_id": "<target uuid>" }

Целевая компания должна входить в available_companies вызывающего (возвращаются при входе), иначе - 403 forbidden. В ответ приходит новая пара access- и refresh-токенов для целевой компании; старый refresh-токен отзывается, и в журнал аудита записывается событие auth.account.swapped.

Многофакторная аутентификация

MFA на основе TOTP можно подключить для отдельного участника и сделать обязательной для всего аккаунта. Когда она включена, POST /auth/login возвращает запрос на подтверждение, а сессия завершается через POST /auth/mfa/verify. Резервные коды выдаются при подключении.

Защита входа

Маршруты входа ограничены 10 попытками с одного IP в минуту и 5 попытками на один e-mail за 15 минут.
Десять неудачных попыток входа блокируют e-mail на 30 минут; ответ содержит code: account_locked.
reCAPTCHA можно включить для отдельных действий (регистрация, вход, сброс пароля); публичная стартовая конфигурация отдаётся по GET /api/v1/captcha.