Автентикација

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.