Autentificare

Chei API (recomandate pentru integrări)

O cheie API este un token de acces personal, legat de un membru al contului tău.

• Creează una în Setări → Pluginuri → Chei API RolChat. Secretul este afișat o singură dată; ulterior sunt vizibile doar primele zece caractere, iar RolChat stochează doar un hash SHA-256.
• Format: rcp_ urmat de 32 de octeți aleatori în base64url, aproximativ 45 de caractere în total. Prefixul face cheia ușor de recunoscut în jurnale și o deosebește de un token de sesiune.
• Domenii de acces: alese dintr-un catalog fix de capabilități la crearea cheii. O cheie nu poate face niciodată mai mult decât membrul care a creat-o: la fiecare apel se verifică ambele condiții, capabilitatea se află în domeniile cheii și membrul o deține încă. Restrângi rolul membrului, iar cheia se restrânge odată cu el.
• Durată de viață: cheile nu expiră singure. Revocă o cheie din pagina de profil sau cu DELETE /api/v1/tokens/:id; revocarea are efect imediat. Nu există rotire pe loc: revocă cheia și creează una nouă.
• Crearea și revocarea sunt înregistrate în jurnalul de audit.

Trimite-o ca token bearer - nu există un antet separat pentru cheile API:

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

Cererile făcute cu o cheie API de plugin sunt limitate la 300 pe minut.

Sesiuni JWT

Aplicația web și SDK-urile mobile se autentifică prin e-mail și parolă (sau Google ori Apple) și primesc o pereche de tokenuri.

Token	Durată de viață	Observații
Token de acces	15 minute	RS256, verificat cu JWKS de la /.well-known/jwks.json
Token de reîmprospătare	30 de zile	Rotit la fiecare reîmprospătare; reutilizarea unui token deja rotit revocă întregul lanț

Claims: sub (utilizator), acc (cont), rl (rol) și, pentru rolurile per site, sts (site-uri permise).

POST /auth/login, /auth/refresh, /auth/swap-company și /auth/logout sunt singurele endpointuri din fluxul de autentificare care nu trebuie să conțină antetul X-Account-Id descris mai jos.

Antetul X-Account-Id

Fiecare cerere autentificată, cu excepția celor patru de mai sus, trebuie să indice contul în numele căruia acționează:

X-Account-Id: <account uuid>

Serverul verifică dacă antetul este egal cu claim-ul acc al tokenului (sau cu contul cheii API). Un antet lipsă produce 400 missing_required_header; o nepotrivire produce 403 account_context_mismatch. Antetul există pentru ca o eroare de client sau un token reutilizat să nu poată citi niciodată pe tăcute datele altui chiriaș: nepotrivirea este respinsă înainte de rularea oricărei interogări, iar fiecare rând de jurnal poate fi atribuit unui cont fără decodarea tokenului.

Utilizatori cu mai multe companii

O persoană poate aparține mai multor companii. Fiecare companie are propriul token (propriul claim acc). Pentru a comuta:

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

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

Ținta trebuie să fie una dintre available_companies ale apelantului (returnate la autentificare), altfel răspunsul este 403 forbidden. Răspunsul conține o nouă pereche de tokenuri de acces și de reîmprospătare, limitată la țintă; vechiul token de reîmprospătare este revocat și se înregistrează un eveniment de audit auth.account.swapped.

Autentificare cu mai mulți factori

MFA bazată pe TOTP poate fi activată per membru și impusă per cont. Când este activă, POST /auth/login returnează o provocare, iar sesiunea se finalizează cu POST /auth/mfa/verify. Codurile de rezervă sunt emise la activare.

Protecția autentificării

• Rutele de autentificare sunt limitate la 10 încercări pe minut per IP și 5 la 15 minute per adresă de e-mail.
• Zece autentificări eșuate blochează adresa de e-mail timp de 30 minute; răspunsul conține code: account_locked.
• reCAPTCHA poate fi activat per acțiune (înscriere, autentificare, resetarea parolei); configurația publică inițială este servită de GET /api/v1/captcha.