Preverjanje pristnosti

Ključi API (priporočeno za integracije)

Ključ API je osebni žeton za dostop, vezan na člana vašega računa.

• Ustvarite ga v Nastavitve → Vtičniki → Ključi API RolChat. Skrivnost je prikazana samo enkrat; nato je vidnih le prvih deset znakov, RolChat pa hrani samo zgoščeno vrednost SHA-256.
• Oblika: rcp_, ki mu sledi 32 naključnih bajtov v base64url, skupaj približno 45 znakov. Zaradi predpone je ključ v dnevnikih lahko prepoznaven in se razlikuje od žetona seje.
• Obsegi: izberejo se ob ustvarjanju ključa iz stalnega kataloga zmožnosti. Ključ nikoli ne zmore več kot član, ki ga je ustvaril: pri vsakem klicu se preverita oba pogoja, zmožnost je v obsegih ključa in član jo še vedno ima. Zožite vlogo člana in ključ se zoži skupaj z njo.
• Življenjska doba: ključi ne potečejo sami. Ključ prekličete na strani profila ali z DELETE /api/v1/tokens/:id; preklic začne veljati takoj. Menjave na mestu ni: prekličite ključ in ustvarite novega.
• Ustvarjanje in preklic se zapišeta v revizijski dnevnik.

Pošljite ga kot žeton bearer - ločene glave za ključ API ni:

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

Zahteve s ključem API vtičnika so omejene na 300 na minuto.

Seje JWT

Spletna aplikacija in mobilni SDK-ji se prijavijo z e-poštnim naslovom in geslom (ali prek Googla ali Appla) in prejmejo par žetonov.

Žeton	Življenjska doba	Opombe
Žeton za dostop	15 minut	RS256, preverjen glede na JWKS na /.well-known/jwks.json
Žeton za osvežitev	30 dni	Zamenja se ob vsaki osvežitvi; ponovna uporaba zamenjanega žetona prekliče celotno verigo

Trditve (claims): sub (uporabnik), acc (račun), rl (vloga) in za vloge, vezane na spletna mesta, sts (dovoljena spletna mesta).

POST /auth/login, /auth/refresh, /auth/swap-company in /auth/logout so edine končne točke postopka preverjanja pristnosti, ki ne smejo vsebovati glave X-Account-Id, opisane v nadaljevanju.

Glava X-Account-Id

Vsaka zahteva s preverjeno pristnostjo razen štirih zgornjih mora navesti račun, v imenu katerega deluje:

X-Account-Id: <account uuid>

Strežnik preveri, ali je glava enaka trditvi acc v žetonu (ali računu ključa API). Manjkajoča glava vrne 400 missing_required_header; neujemanje vrne 403 account_context_mismatch. Glava obstaja zato, da napaka odjemalca ali ponovno uporabljen žeton nikoli ne moreta tiho prebrati podatkov drugega najemnika: neujemanje je zavrnjeno, preden se izvede katera koli poizvedba, vsako vrstico dnevnika pa je mogoče pripisati računu brez dekodiranja žetona.

Uporabniki več podjetij

Ena oseba lahko pripada več podjetjem. Vsako podjetje ima svoj žeton (svojo trditev acc). Za preklop:

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

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

Ciljno podjetje mora biti med available_companies klicatelja (vrnjena ob prijavi), sicer je odgovor 403 forbidden. Odgovor je nov par žetona za dostop in žetona za osvežitev za ciljno podjetje; stari žeton za osvežitev se prekliče in zapiše se revizijski dogodek auth.account.swapped.

Večfaktorsko preverjanje pristnosti

MFA na osnovi TOTP lahko vklopi vsak član, račun pa ga lahko zahteva. Ko je vklopljeno, POST /auth/login vrne izziv, sejo pa dokonča POST /auth/mfa/verify. Rezervne kode se izdajo ob vklopu.

Zaščita prijave

• Poti za prijavo so omejene na 10 poskusov na IP naslov na minuto in 5 na e-poštni naslov na 15 minut.
• Deset neuspešnih prijav zaklene e-poštni naslov za 30 minut; odgovor vsebuje code: account_locked.
• reCAPTCHA je mogoče vklopiti za posamezna dejanja (registracija, prijava, ponastavitev gesla); javna začetna konfiguracija je na voljo na GET /api/v1/captcha.