Autentifikacija

API ključevi (preporučeno za integracije)

API ključ je osobni pristupni token vezan uz člana vašeg računa.

• Izradite ga u Postavke → Dodaci → RolChat API ključevi. Tajna se prikazuje samo jednom; nakon toga vidljivo je samo prvih deset znakova, a RolChat pohranjuje samo SHA-256 sažetak.
• Format: rcp_ nakon kojeg slijede 32 nasumična bajta u base64url, ukupno oko 45 znakova. Zahvaljujući prefiksu ključ je lako prepoznati u zapisnicima i razlikovati od tokena sesije.
• Opsezi: biraju se pri izradi ključa iz fiksnog kataloga ovlasti. Ključ nikada ne može više od člana koji ga je izradio: pri svakom pozivu provjeravaju se oba uvjeta, ovlast je u opsezima ključa i član je i dalje ima. Suzite ulogu člana i ključ se sužava zajedno s njom.
• Trajanje: ključevi ne istječu sami. Ključ opozovite na stranici profila ili pomoću DELETE /api/v1/tokens/:id; opoziv djeluje odmah. Nema rotacije na mjestu: opozovite ključ i izradite novi.
• Izrada i opoziv bilježe se u revizijski zapisnik.

Šaljite ga kao bearer token - ne postoji zasebno zaglavlje za API ključ:

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

Zahtjevi s API ključem dodatka ograničeni su na 300 u minuti.

JWT sesije

Web aplikacija i mobilni SDK-ovi prijavljuju se e-poštom i lozinkom (ili putem Googlea ili Applea) i dobivaju par tokena.

Token	Trajanje	Napomene
Pristupni token	15 minuta	RS256, provjerava se prema JWKS-u na /.well-known/jwks.json
Token za osvježavanje	30 dana	Mijenja se pri svakom osvježavanju; ponovna uporaba zamijenjenog tokena opoziva cijeli lanac

Tvrdnje (claims): sub (korisnik), acc (račun), rl (uloga) te, za uloge vezane uz stranice, sts (dopuštene stranice).

POST /auth/login, /auth/refresh, /auth/swap-company i /auth/logout jedine su krajnje točke tijeka autentifikacije koje ne smiju sadržavati zaglavlje X-Account-Id opisano u nastavku.

Zaglavlje X-Account-Id

Svaki autentificirani zahtjev osim četiri gore navedena mora navesti račun u čije ime djeluje:

X-Account-Id: <account uuid>

Poslužitelj provjerava je li zaglavlje jednako tvrdnji acc u tokenu (ili računu API ključa). Nedostajuće zaglavlje vraća 400 missing_required_header; nepodudaranje vraća 403 account_context_mismatch. Zaglavlje postoji kako greška klijenta ili ponovno upotrijebljen token nikada ne bi mogli tiho pročitati podatke drugog zakupca: nepodudaranje se odbija prije izvršavanja ijednog upita, a svaki redak zapisnika može se pripisati računu bez dekodiranja tokena.

Korisnici s više tvrtki

Jedna osoba može pripadati većem broju tvrtki. Svaka tvrtka ima vlastiti token (vlastitu tvrdnju acc). Za prebacivanje:

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

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

Ciljna tvrtka mora biti među available_companies pozivatelja (vraćaju se pri prijavi), inače je odgovor 403 forbidden. Odgovor je novi par pristupnog tokena i tokena za osvježavanje za ciljnu tvrtku; stari token za osvježavanje se opoziva i bilježi se revizijski događaj auth.account.swapped.

Višefaktorska autentifikacija

MFA temeljen na TOTP-u može aktivirati svaki član, a račun ga može zahtijevati. Kada je uključen, POST /auth/login vraća izazov, a sesiju dovršava POST /auth/mfa/verify. Rezervni kodovi izdaju se pri aktivaciji.

Zaštita prijave

• Rute za prijavu ograničene su na 10 pokušaja po IP adresi u minuti i 5 po adresi e-pošte u 15 minuta.
• Deset neuspjelih prijava zaključava adresu e-pošte na 30 minuta; odgovor sadrži code: account_locked.
• reCAPTCHA se može uključiti za pojedine radnje (registracija, prijava, poništavanje lozinke); javna početna konfiguracija poslužuje se s GET /api/v1/captcha.