Автентифікація

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.