Autentifikācija

API atslēgas (ieteicams integrācijām)

API atslēga ir personīgās piekļuves marķieris, kas piesaistīts jūsu konta dalībniekam.

• Izveidojiet to sadaļā Iestatījumi → Spraudņi → RolChat API atslēgas. Noslēpums tiek parādīts vienreiz; pēc tam redzamas tikai tā pirmās desmit rakstzīmes, un RolChat glabā tikai SHA-256 jaucējvērtību.
• Formāts: rcp_, kam seko 32 nejauši baiti base64url kodējumā, kopā apmēram 45 rakstzīmes. Prefikss padara atslēgu atpazīstamu žurnālos un atšķirīgu no sesijas marķiera.
• Tvērumi: tiek izvēlēti no noteikta iespēju kataloga, veidojot atslēgu. Atslēga nekad nevar izdarīt vairāk nekā dalībnieks, kurš to izveidoja: katrā izsaukumā tiek pārbaudīti abi nosacījumi, iespēja ir atslēgas tvērumos un dalībniekam tā joprojām ir. Sašauriniet dalībnieka lomu, un atslēga sašaurinās līdz ar to.
• Derīguma termiņš: atslēgas pašas nebeidzas. Atsauciet atslēgu profila lapā vai ar DELETE /api/v1/tokens/:id; atsaukšana stājas spēkā nekavējoties. Rotācijas uz vietas nav: atsauciet un izveidojiet jaunu atslēgu.
• Izveide un atsaukšana tiek ierakstītas audita žurnālā.

Sūtiet to kā bearer marķieri - atsevišķas API atslēgas galvenes nav:

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

Pieprasījumi ar spraudņa API atslēgu ir ierobežoti līdz 300 minūtē.

JWT sesijas

Tīmekļa lietotne un mobilie SDK piesakās ar e-pastu un paroli (vai Google vai Apple) un saņem marķieru pāri.

Marķieris	Derīguma termiņš	Piezīmes
Piekļuves marķieris	15 minūtes	RS256, pārbaudīts pret JWKS adresē /.well-known/jwks.json
Atsvaidzināšanas marķieris	30 dienas	Tiek rotēts katrā atsvaidzināšanā; rotēta marķiera atkārtota izmantošana atsauc visu ķēdi

Apgalvojumi: sub (lietotājs), acc (konts), rl (loma) un vietnes līmeņa lomām sts (atļautās vietnes).

POST /auth/login, /auth/refresh, /auth/swap-company un /auth/logout ir vienīgie autentifikācijas plūsmas galapunkti, kuriem nedrīkst būt tālāk aprakstītā galvene X-Account-Id.

Galvene X-Account-Id

Katram autentificētam pieprasījumam, izņemot četrus iepriekš minētos, jānorāda konts, kurā tas darbojas:

X-Account-Id: <account uuid>

Serveris pārbauda, vai galvene sakrīt ar marķiera apgalvojumu acc (vai API atslēgas kontu). Trūkstoša galvene ir 400 missing_required_header; neatbilstība ir 403 account_context_mismatch. Galvene pastāv, lai klienta kļūda vai atkārtoti izmantots marķieris nekad nevarētu klusi nolasīt cita nomnieka datus: neatbilstība tiek noraidīta, pirms tiek izpildīts jebkurš vaicājums, un katru žurnāla rindu var attiecināt uz kontu, neatkodējot marķieri.

Lietotāji ar vairākiem uzņēmumiem

Viens cilvēks var piederēt vairākiem uzņēmumiem. Katram uzņēmumam ir savs marķieris (savs apgalvojums acc). Lai pārslēgtos:

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

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

Mērķim jābūt vienam no izsaucēja available_companies (tiek atgriezti pieteikšanās brīdī), citādi 403 forbidden. Atbilde ir jauns piekļuves un atsvaidzināšanas marķieru pāris mērķa kontam; vecais atsvaidzināšanas marķieris tiek atsaukts, un tiek ierakstīts audita notikums auth.account.swapped.

Daudzfaktoru autentifikācija

Uz TOTP balstītu MFA var reģistrēt katram dalībniekam un pieprasīt visam kontam. Kad tā ir ieslēgta, POST /auth/login atgriež izaicinājumu, un sesija tiek pabeigta ar POST /auth/mfa/verify. Reģistrējoties tiek izsniegti rezerves kodi.

Pieteikšanās aizsardzība

• Pieteikšanās maršruti ir ierobežoti līdz 10 mēģinājumiem no IP minūtē un 5 uz e-pastu 15 minūtēs.
• Desmit neveiksmīgas pieteikšanās bloķē e-pastu uz 30 minūtēm; atbildē ir code: account_locked.
• reCAPTCHA var ieslēgt katrai darbībai (reģistrācija, pieteikšanās, paroles atiestatīšana); publiskā sākotnējā konfigurācija tiek sniegta no GET /api/v1/captcha.