Autentifikavimas

API raktai (rekomenduojami integracijoms)

API raktas yra asmeninis prieigos žetonas, susietas su jūsų paskyros nariu.

• Sukurkite jį skiltyje Nustatymai → Įskiepiai → RolChat API raktai. Paslaptis parodoma vieną kartą; vėliau matomi tik pirmi dešimt jos simbolių, o RolChat saugo tik SHA-256 maišą.
• Formatas: rcp_ ir 32 atsitiktiniai baitai base64url formatu, iš viso apie 45 simbolius. Priešdėlis leidžia atpažinti raktą žurnaluose ir atskirti jį nuo sesijos žetono.
• Aprėptys: kuriant raktą pasirenkamos iš fiksuoto galimybių katalogo. Raktas niekada negali padaryti daugiau nei jį sukūręs narys: kiekvieno iškvietimo metu tikrinamos abi sąlygos, galimybė yra rakto aprėptyse ir narys ją vis dar turi. Susiaurinus nario vaidmenį, kartu susiaurėja ir raktas.
• Galiojimas: raktai savaime nenustoja galioti. Atšaukite raktą profilio puslapyje arba su DELETE /api/v1/tokens/:id; atšaukimas įsigalioja iškart. Rakto pakeitimo vietoje nėra: atšaukite ir sukurkite naują raktą.
• Sukūrimas ir atšaukimas įrašomi į audito žurnalą.

Siųskite jį kaip bearer žetoną - atskiros API rakto antraštės nėra:

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

Užklausos su įskiepio API raktu ribojamos iki 300 per minutę.

JWT sesijos

Žiniatinklio programa ir mobilieji SDK prisijungia el. paštu ir slaptažodžiu (arba per Google ar Apple) ir gauna žetonų porą.

Žetonas	Galiojimas	Pastabos
Prieigos žetonas	15 minučių	RS256, tikrinamas pagal JWKS adresu /.well-known/jwks.json
Atnaujinimo žetonas	30 dienų	Keičiamas kiekvieno atnaujinimo metu; pakartotinai panaudojus pakeistą žetoną, atšaukiama visa grandinė

Teiginiai: sub (naudotojas), acc (paskyra), rl (vaidmuo) ir, svetainės lygio vaidmenims, sts (leidžiamos svetainės).

POST /auth/login, /auth/refresh, /auth/swap-company ir /auth/logout yra vieninteliai autentifikavimo srauto galiniai taškai, kurie neturi turėti toliau aprašytos antraštės X-Account-Id.

Antraštė X-Account-Id

Kiekviena autentifikuota užklausa, išskyrus keturias aukščiau paminėtas, turi nurodyti paskyrą, kurios vardu veikia:

X-Account-Id: <account uuid>

Serveris tikrina, ar antraštė sutampa su žetono teiginiu acc (arba API rakto paskyra). Trūkstama antraštė yra 400 missing_required_header; nesutapimas yra 403 account_context_mismatch. Antraštė egzistuoja tam, kad kliento klaida ar pakartotinai panaudotas žetonas niekada negalėtų tyliai nuskaityti kito nuomininko duomenų: nesutapimas atmetamas prieš vykdant bet kokią užklausą, o kiekvieną žurnalo eilutę galima priskirti paskyrai neiškoduojant žetono.

Naudotojai keliose įmonėse

Vienas asmuo gali priklausyti kelioms įmonėms. Kiekviena įmonė turi savo žetoną (savo teiginį acc). Norėdami persijungti:

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

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

Tikslinė įmonė turi būti viena iš iškvietėjo available_companies (grąžinamų prisijungiant), kitaip 403 forbidden. Atsakymas yra nauja prieigos ir atnaujinimo žetonų pora, skirta tikslinei įmonei; senas atnaujinimo žetonas atšaukiamas ir įrašomas audito įvykis auth.account.swapped.

Kelių veiksnių autentifikavimas

TOTP pagrįstą MFA galima užregistruoti kiekvienam nariui ir padaryti privalomą visai paskyrai. Kai ji įjungta, POST /auth/login grąžina iššūkį, o sesija užbaigiama su POST /auth/mfa/verify. Registruojant išduodami atsarginiai kodai.

Prisijungimo apsauga

• Prisijungimo maršrutai ribojami iki 10 bandymų per minutę vienam IP ir 5 per 15 minučių vienam el. pašto adresui.
• Dešimt nesėkmingų prisijungimų užrakina el. pašto adresą 30 minučių; atsakyme yra code: account_locked.
• reCAPTCHA galima įjungti kiekvienam veiksmui (registracija, prisijungimas, slaptažodžio atkūrimas); vieša pradinė konfigūracija pateikiama iš GET /api/v1/captcha.