Autentimine

API-võtmed (soovitatav integratsioonide jaoks)

API-võti on isiklik juurdepääsuluba, mis on seotud sinu konto liikmega.

• Loo see jaotises Seaded → Pistikprogrammid → RolChati API-võtmed. Saladust näidatakse üks kord; pärast seda on nähtavad ainult selle esimesed kümme märki ja RolChat salvestab ainult SHA-256 räsi.
• Vorming: rcp_, millele järgneb 32 juhuslikku baiti base64url-kodeeringus, kokku umbes 45 märki. Eesliide teeb võtme logides äratuntavaks ja eristab seda seansitokenist.
• Ulatused: valitakse võtme loomisel võimekuste fikseeritud kataloogist. Võti ei saa kunagi teha rohkem kui liige, kes selle lõi: iga väljakutse korral kontrollitakse mõlemat tingimust, võimekus on võtme ulatustes ja liikmel on see endiselt olemas. Kitsenda liikme rolli ja võti kitseneb koos sellega.
• Eluiga: võtmed ei aegu iseenesest. Tühista võti profiililehelt või käsuga DELETE /api/v1/tokens/:id; tühistamine jõustub kohe. Kohapealset vahetamist pole: tühista ja loo uus võti.
• Loomine ja tühistamine kirjutatakse auditilogisse.

Saada see bearer-tokenina - eraldi API-võtme päist pole:

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

Pistikprogrammi API-võtmega päringud on piiratud 300-ga minutis.

JWT-seansid

Veebirakendus ja mobiili-SDK-d logivad sisse e-posti ja parooliga (või Google’i või Apple’iga) ning saavad tokenipaari.

Token	Eluiga	Märkused
Juurdepääsutoken	15 minutit	RS256, kontrollitakse JWKS-i vastu aadressil /.well-known/jwks.json
Värskendustoken	30 päeva	Vahetatakse iga värskendamisega; vahetatud tokeni taaskasutamine tühistab kogu ahela

Väited: sub (kasutaja), acc (konto), rl (roll) ja saidipõhiste rollide puhul sts (lubatud saidid).

POST /auth/login, /auth/refresh, /auth/swap-company ja /auth/logout on ainsad autentimisvoo lõpp-punktid, mis ei tohi kanda järgmisena kirjeldatud päist X-Account-Id.

Päis X-Account-Id

Iga autenditud päring peale nelja ülalnimetatu peab kandma kontot, mille nimel see tegutseb:

X-Account-Id: <account uuid>

Server kontrollib, et päis võrduks tokeni väitega acc (või API-võtme kontoga). Puuduv päis on 400 missing_required_header; mittevastavus on 403 account_context_mismatch. Päis on olemas selleks, et kliendi viga või taasesitatud token ei saaks kunagi vaikselt lugeda teise rentniku andmeid: mittevastavus lükatakse tagasi enne ühegi päringu käivitamist ja iga logirida on kontoga seostatav ilma tokenit dekodeerimata.

Mitme ettevõttega kasutajad

Üks inimene võib kuuluda mitmesse ettevõttesse. Igal ettevõttel on oma token (oma väide acc). Vahetamiseks:

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

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

Sihtmärk peab olema üks väljakutsuja available_companies hulgast (tagastatakse sisselogimisel), muidu 403 forbidden. Vastus on uus juurdepääsu- ja värskendustokeni paar, mis on piiratud sihtmärgiga; vana värskendustoken tühistatakse ja kirjutatakse auditisündmus auth.account.swapped.

Mitmeastmeline autentimine

TOTP-põhise MFA saab registreerida liikme kaupa ja nõuda konto kaupa. Kui see on sees, tagastab POST /auth/login väljakutse ja seanss lõpetatakse käsuga POST /auth/mfa/verify. Varukoodid väljastatakse registreerimisel.

Sisselogimise kaitse

• Sisselogimisteed on piiratud 10 katsega IP kohta minutis ja 5 katsega e-posti kohta 15 minuti jooksul.
• Kümme ebaõnnestunud sisselogimist lukustavad e-posti aadressi 30 minutiks; vastus kannab code: account_locked.
• reCAPTCHA saab lubada toimingu kaupa (registreerumine, sisselogimine, parooli lähtestamine); avalik algkonfiguratsioon serveeritakse aadressilt GET /api/v1/captcha.