Autentisering

API-nøkler (anbefalt for integrasjoner)

En API-nøkkel er et personlig tilgangstoken knyttet til et medlem av kontoen din.

• Opprett en i Innstillinger → Plugins → RolChat API-nøkler. Hemmeligheten vises én gang; deretter er bare de ti første tegnene synlige, og RolChat lagrer bare en SHA-256-hash.
• Format: rcp_ etterfulgt av 32 tilfeldige byte i base64url, omtrent 45 tegn til sammen. Prefikset gjør at en nøkkel er lett å kjenne igjen i logger og skiller seg fra et økttoken.
• Tilgangsomfang (scopes): velges fra en fast katalog over funksjoner når nøkkelen opprettes. En nøkkel kan aldri gjøre mer enn medlemmet som opprettet den: ved hvert kall kontrolleres begge betingelsene, funksjonen er i nøkkelens omfang og medlemmet har den fortsatt. Innskrenker du medlemmets rolle, innskrenkes nøkkelen tilsvarende.
• Levetid: nøkler utløper ikke av seg selv. Tilbakekall en nøkkel fra profilsiden eller med DELETE /api/v1/tokens/:id; tilbakekallingen trer i kraft umiddelbart. Det finnes ingen rotasjon på stedet: tilbakekall og opprett en ny nøkkel.
• Oppretting og tilbakekalling skrives til revisjonsloggen.

Send den som et bearer-token - det finnes ingen egen header for API-nøkler:

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

Forespørsler med en plugin-API-nøkkel er begrenset til 300 per minutt.

JWT-økter

Nettappen og mobil-SDK-ene logger inn med e-post og passord (eller Google eller Apple) og mottar et tokenpar.

Token	Levetid	Merknader
Tilgangstoken	15 minutter	RS256, verifisert mot JWKS på /.well-known/jwks.json
Fornyelsestoken	30 dager	Roteres ved hver fornyelse; gjenbruk av et rotert token tilbakekaller hele kjeden

Claims: sub (bruker), acc (konto), rl (rolle) og, for roller per nettsted, sts (tillatte nettsteder).

POST /auth/login, /auth/refresh, /auth/swap-company og /auth/logout er de eneste endepunktene i autentiseringsflyten som ikke skal ha headeren X-Account-Id som beskrives nedenfor.

Headeren X-Account-Id

Hver autentisert forespørsel unntatt de fire ovenfor må angi kontoen den handler på vegne av:

X-Account-Id: <account uuid>

Serveren kontrollerer at headeren er lik acc-claimet i tokenet (eller kontoen til API-nøkkelen). En manglende header gir 400 missing_required_header; et avvik gir 403 account_context_mismatch. Headeren finnes for at en klientfeil eller et gjenbrukt token aldri skal kunne lese en annen kundes data i det stille: avviket avvises før noen spørring kjøres, og hver logglinje kan knyttes til en konto uten å dekode tokenet.

Brukere i flere selskaper

Én person kan tilhøre flere selskaper. Hvert selskap har sitt eget token (sitt eget acc-claim). Slik bytter du:

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

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

Målet må være ett av anroperens available_companies (returneres ved innlogging), ellers 403 forbidden. Svaret er et nytt par med tilgangstoken og fornyelsestoken for målselskapet; det gamle fornyelsestokenet tilbakekalles, og en revisjonshendelse auth.account.swapped skrives.

Flerfaktorautentisering

TOTP-basert MFA kan aktiveres per medlem og kreves per konto. Når det er slått på, returnerer POST /auth/login en utfordring, og økten fullføres med POST /auth/mfa/verify. Reservekoder utstedes ved aktiveringen.

Beskyttelse av innlogging

• Innloggingsrutene er begrenset til 10 forsøk per IP per minutt og 5 per e-postadresse per 15 minutter.
• Ti mislykkede innlogginger låser e-postadressen i 30 minutter; svaret inneholder code: account_locked.
• reCAPTCHA kan aktiveres per handling (registrering, innlogging, tilbakestilling av passord); den offentlige oppstartskonfigurasjonen leveres fra GET /api/v1/captcha.