Verifikasie

API-sleutels (aanbeveel vir integrasies)

’n API-sleutel is ’n persoonlike toegangstoken wat aan ’n lid van jou rekening gekoppel is.

• Skep een in Instellings → Inproppe → RolChat API-sleutels. Die geheim word een keer gewys; daarna is slegs die eerste tien karakters sigbaar, en RolChat stoor slegs ’n SHA-256-hash.
• Formaat: rcp_ gevolg deur 32 ewekansige grepe in base64url, sowat 45 karakters in totaal. Die voorvoegsel maak ’n sleutel in logs herkenbaar en onderskei dit van ’n sessietoken.
• Omvange: gekies uit ’n vaste katalogus van vermoëns wanneer die sleutel geskep word. ’n Sleutel kan nooit meer doen as die lid wat dit geskep het nie: by elke oproep word albei voorwaardes nagegaan, die vermoë is in die sleutel se omvange en die lid het dit steeds. Beperk die lid se rol en die sleutel word saam beperk.
• Leeftyd: sleutels verval nie vanself nie. Herroep ’n sleutel op die profielbladsy of met DELETE /api/v1/tokens/:id; herroeping tree onmiddellik in werking. Daar is geen rotasie in plek nie: herroep en skep ’n nuwe sleutel.
• Skepping en herroeping word in die ouditlog aangeteken.

Stuur dit as ’n draertoken - daar is geen aparte API-sleutelopskrif nie:

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

Versoeke met ’n inprop-API-sleutel is beperk tot 300 per minuut.

JWT-sessies

Die webprogram en die mobiele SDK’s meld aan met e-pos en wagwoord (of Google of Apple) en ontvang ’n tokenpaar.

Token	Leeftyd	Notas
Toegangstoken	15 minute	RS256, geverifieer teen die JWKS by /.well-known/jwks.json
Verfristoken	30 dae	Word by elke verfrissing geroteer; hergebruik van ’n geroteerde token herroep die hele ketting

Aansprake: sub (gebruiker), acc (rekening), rl (rol) en, vir rolle per webwerf, sts (toegelate webwerwe).

POST /auth/login, /auth/refresh, /auth/swap-company en /auth/logout is die enigste eindpunte in die verifikasievloei wat nie die X-Account-Id-opskrif wat hierna beskryf word, mag dra nie.

Die X-Account-Id-opskrif

Elke geverifieerde versoek behalwe die vier hierbo moet die rekening dra waarop dit optree:

X-Account-Id: <account uuid>

Die bediener kontroleer dat die opskrif gelyk is aan die token se acc-aanspraak (of die API-sleutel se rekening). ’n Ontbrekende opskrif is 400 missing_required_header; ’n wanpassing is 403 account_context_mismatch. Die opskrif bestaan sodat ’n kliëntfout of ’n herspeelde token nooit stilweg ’n ander huurder se data kan lees nie: die wanpassing word verwerp voordat enige navraag loop, en elke logreël kan aan ’n rekening toegeskryf word sonder om die token te dekodeer.

Gebruikers met verskeie maatskappye

Een persoon kan aan verskeie maatskappye behoort. Elke maatskappy het sy eie token (sy eie acc-aanspraak). Om te wissel:

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

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

Die teiken moet een van die roeper se available_companies wees (by aanmelding teruggegee), anders 403 forbidden. Die antwoord is ’n nuwe paar toegangs- en verfristokens wat tot die teiken beperk is; die ou verfristoken word herroep en ’n auth.account.swapped-ouditgebeurtenis word aangeteken.

Multifaktor-verifikasie

TOTP-gebaseerde MFA kan per lid ingeskryf en per rekening vereis word. Wanneer dit aan is, gee POST /auth/login ’n uitdaging terug en die sessie word met POST /auth/mfa/verify voltooi. Rugsteunkodes word by inskrywing uitgereik.

Aanmeldbeskerming

• Aanmeldroetes is beperk tot 10 pogings per IP per minuut en 5 per e-pos per 15 minute.
• Tien mislukte aanmeldings sluit die e-posadres vir 30 minute; die antwoord dra code: account_locked.
• reCAPTCHA kan per aksie geaktiveer word (registrasie, aanmelding, wagwoordherstel); die publieke selflaaikonfigurasie word vanaf GET /api/v1/captcha bedien.