Ověřování

Klíče API (doporučené pro integrace)

Klíč API je osobní přístupový token vázaný na člena vašeho účtu.

Vytvoříte ho v Nastavení → Pluginy → Klíče API RolChat. Tajný klíč se zobrazí jen jednou; poté je vidět jen jeho prvních deset znaků a RolChat ukládá pouze hash SHA-256.
Formát: rcp_ následované 32 náhodnými bajty v base64url, celkem asi 45 znaků. Díky prefixu je klíč v logech snadno rozpoznatelný a odlišitelný od tokenu relace.
Rozsahy: vybírají se při vytvoření klíče z pevného katalogu oprávnění. Klíč nikdy nesmí víc než člen, který ho vytvořil: při každém volání se ověřují obě podmínky, tedy že oprávnění je v rozsazích klíče a že ho člen stále má. Když členovi zúžíte roli, zúží se s ní i klíč.
Životnost: klíče samy nevyprší. Klíč zrušíte na stránce profilu nebo přes DELETE /api/v1/tokens/:id; zrušení platí okamžitě. Rotace na místě neexistuje: klíč zrušte a vytvořte nový.
Vytvoření i zrušení se zapisuje do auditního logu.

Posílejte ho jako bearer token - samostatná hlavička pro klíč API neexistuje:

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

Požadavky s klíčem API pluginu jsou omezeny na 300 za minutu.

Relace JWT

Webová aplikace a mobilní SDK se přihlašují e-mailem a heslem (nebo přes Google či Apple) a dostanou pár tokenů.

Token	Životnost	Poznámky
Přístupový token	15 minut	RS256, ověřuje se vůči JWKS na `/.well-known/jwks.json`
Obnovovací token	30 dní	Mění se při každém obnovení; opětovné použití vyměněného tokenu zruší celý řetězec

Claimy: sub (uživatel), acc (účet), rl (role) a u rolí vázaných na weby sts (povolené weby).

POST /auth/login, /auth/refresh, /auth/swap-company a /auth/logout jsou jediné endpointy ověřovacího toku, které nesmí obsahovat hlavičku X-Account-Id popsanou dále.

Hlavička `X-Account-Id`

Každý ověřený požadavek kromě čtyř výše uvedených musí uvádět účet, jehož jménem jedná:

X-Account-Id: <account uuid>

Server kontroluje, že hlavička odpovídá claimu acc v tokenu (nebo účtu klíče API). Chybějící hlavička vrací 400 missing_required_header; neshoda vrací 403 account_context_mismatch. Hlavička existuje proto, aby chyba klienta nebo znovu použitý token nikdy nemohly potichu přečíst data jiného tenanta: neshoda se odmítne dřív, než proběhne jakýkoli dotaz, a každý řádek logu lze přiřadit k účtu bez dekódování tokenu.

Uživatelé více firem

Jedna osoba může patřit do několika firem. Každá firma má vlastní token (vlastní claim acc). Přepnutí:

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

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

Cílová firma musí být mezi available_companies volajícího (vrací se při přihlášení), jinak odpověď zní 403 forbidden. Odpovědí je nový pár přístupového a obnovovacího tokenu pro cílovou firmu; starý obnovovací token je zrušen a zapíše se auditní událost auth.account.swapped.

Vícefaktorové ověření

MFA založené na TOTP si může nastavit každý člen a účet ho může vyžadovat. Když je zapnuté, POST /auth/login vrátí výzvu a relaci dokončí POST /auth/mfa/verify. Záložní kódy se vydávají při nastavení.

Ochrana přihlášení

Přihlašovací trasy jsou omezeny na 10 pokusů z jedné IP za minutu a 5 na e-mail za 15 minut.
Deset neúspěšných přihlášení zablokuje e-mail na 30 minut; odpověď obsahuje code: account_locked.
reCAPTCHA lze zapnout pro jednotlivé akce (registrace, přihlášení, obnova hesla); veřejná výchozí konfigurace se poskytuje z GET /api/v1/captcha.