Overovanie

Kľúče API (odporúčané pre integrácie)

Kľúč API je osobný prístupový token viazaný na člena vášho účtu.

• Vytvoríte ho v Nastavenia → Pluginy → Kľúče API RolChat. Tajný kľúč sa zobrazí iba raz; potom je viditeľných len jeho prvých desať znakov a RolChat ukladá iba hash SHA-256.
• Formát: rcp_ a za ním 32 náhodných bajtov v base64url, spolu asi 45 znakov. Vďaka prefixu je kľúč v logoch ľahko rozpoznateľný a odlíšiteľný od tokenu relácie.
• Rozsahy: vyberajú sa pri vytvorení kľúča z pevného katalógu oprávnení. Kľúč nikdy nesmie viac než člen, ktorý ho vytvoril: pri každom volaní sa overujú obe podmienky, teda že oprávnenie je v rozsahoch kľúča a že ho člen stále má. Keď členovi zúžite rolu, zúži sa s ňou aj kľúč.
• Životnosť: kľúče samy neexpirujú. Kľúč zrušíte na stránke profilu alebo cez DELETE /api/v1/tokens/:id; zrušenie platí okamžite. Rotácia na mieste neexistuje: kľúč zrušte a vytvorte nový.
• Vytvorenie aj zrušenie sa zapisuje do auditného logu.

Posielajte ho ako bearer token - samostatná hlavička pre kľúč API neexistuje:

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

Požiadavky s kľúčom API pluginu sú obmedzené na 300 za minútu.

Relácie JWT

Webová aplikácia a mobilné SDK sa prihlasujú e-mailom a heslom (alebo cez Google či Apple) a dostanú pár tokenov.

Token	Životnosť	Poznámky
Prístupový token	15 minút	RS256, overuje sa voči JWKS na /.well-known/jwks.json
Obnovovací token	30 dní	Mení sa pri každom obnovení; opätovné použitie vymeneného tokenu zruší celú reťaz

Claimy: sub (používateľ), acc (účet), rl (rola) a pri rolách viazaných na weby sts (povolené weby).

POST /auth/login, /auth/refresh, /auth/swap-company a /auth/logout sú jediné endpointy overovacieho toku, ktoré nesmú obsahovať hlavičku X-Account-Id opísanú ďalej.

Hlavička X-Account-Id

Každá overená požiadavka okrem štyroch vyššie uvedených musí uvádzať účet, v mene ktorého koná:

X-Account-Id: <account uuid>

Server kontroluje, či sa hlavička zhoduje s claimom acc v tokene (alebo s účtom kľúča API). Chýbajúca hlavička vráti 400 missing_required_header; nezhoda vráti 403 account_context_mismatch. Hlavička existuje preto, aby chyba klienta alebo znovu použitý token nikdy nemohli potichu prečítať dáta iného tenanta: nezhoda sa odmietne skôr, ako sa spustí akýkoľvek dotaz, a každý riadok logu možno priradiť k účtu bez dekódovania tokenu.

Používatelia viacerých firiem

Jedna osoba môže patriť do viacerých firiem. Každá firma má vlastný token (vlastný claim acc). Prepnutie:

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

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

Cieľová firma musí byť medzi available_companies volajúceho (vracajú sa pri prihlásení), inak odpoveď znie 403 forbidden. Odpoveďou je nový pár prístupového a obnovovacieho tokenu pre cieľovú firmu; starý obnovovací token sa zruší a zapíše sa auditná udalosť auth.account.swapped.

Viacfaktorové overenie

MFA založené na TOTP si môže nastaviť každý člen a účet ho môže vyžadovať. Keď je zapnuté, POST /auth/login vráti výzvu a reláciu dokončí POST /auth/mfa/verify. Záložné kódy sa vydávajú pri nastavení.

Ochrana prihlásenia

• Prihlasovacie trasy sú obmedzené na 10 pokusov z jednej IP za minútu a 5 na e-mail za 15 minút.
• Desať neúspešných prihlásení zablokuje e-mail na 30 minút; odpoveď obsahuje code: account_locked.
• reCAPTCHA možno zapnúť pre jednotlivé akcie (registrácia, prihlásenie, obnovenie hesla); verejná štartovacia konfigurácia sa poskytuje z GET /api/v1/captcha.