Удостоверяване

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 влизат с имейл и парола (или чрез 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 опита за един имейл на 15 минути.
Десет неуспешни опита за влизане заключват имейла за 30 минути; отговорът съдържа code: account_locked.
reCAPTCHA може да се включи за отделни действия (регистрация, влизане, нулиране на парола); публичната начална конфигурация се предоставя от GET /api/v1/captcha.