Authenticatie

API-sleutels (aanbevolen voor integraties)

Een API-sleutel is een persoonlijk toegangstoken dat aan een lid van je account is gekoppeld.

• Aanmaken doe je in Instellingen → Plug-ins → RolChat-API-sleutels. Het geheim wordt één keer getoond; daarna zijn alleen de eerste tien tekens zichtbaar, en RolChat bewaart alleen een SHA-256-hash.
• Formaat: rcp_ gevolgd door 32 willekeurige bytes in base64url, in totaal ongeveer 45 tekens. Door het voorvoegsel is een sleutel herkenbaar in logboeken en te onderscheiden van een sessietoken.
• Scopes: gekozen uit een vaste catalogus van functies bij het aanmaken van de sleutel. Een sleutel kan nooit meer dan het lid dat hem heeft aangemaakt: bij elke aanroep worden beide voorwaarden gecontroleerd, de functie zit in de scopes van de sleutel en het lid heeft die nog. Beperk je de rol van het lid, dan wordt de sleutel mee beperkt.
• Levensduur: sleutels verlopen niet vanzelf. Trek een sleutel in via de profielpagina of met DELETE /api/v1/tokens/:id; intrekken werkt direct. Er is geen rotatie ter plekke: trek de sleutel in en maak een nieuwe aan.
• Aanmaken en intrekken worden in het auditlogboek vastgelegd.

Stuur de sleutel mee als bearer-token - er is geen aparte header voor API-sleutels:

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

Verzoeken met een API-sleutel van een plug-in zijn beperkt tot 300 per minuut.

JWT-sessies

De webapp en de mobiele SDK’s loggen in met e-mailadres en wachtwoord (of Google of Apple) en krijgen een tokenpaar.

Token	Levensduur	Opmerkingen
Toegangstoken	15 minuten	RS256, gecontroleerd tegen de JWKS op /.well-known/jwks.json
Vernieuwingstoken	30 dagen	Bij elke vernieuwing geroteerd; hergebruik van een geroteerd token trekt de hele keten in

Claims: sub (gebruiker), acc (account), rl (rol) en, voor rollen per site, sts (toegestane sites).

POST /auth/login, /auth/refresh, /auth/swap-company en /auth/logout zijn de enige endpoints in de authenticatieflow die de hieronder beschreven header X-Account-Id niet mogen bevatten.

De header X-Account-Id

Elk geauthenticeerd verzoek, behalve de vier hierboven, moet het account bevatten waarvoor het werkt:

X-Account-Id: <account uuid>

De server controleert of de header gelijk is aan de claim acc van het token (of aan het account van de API-sleutel). Een ontbrekende header geeft 400 missing_required_header; een afwijking geeft 403 account_context_mismatch. De header bestaat zodat een bug in een client of een opnieuw afgespeeld token nooit ongemerkt gegevens van een andere tenant kan lezen: de afwijking wordt geweigerd voordat er een query draait, en elke logregel is aan een account toe te schrijven zonder het token te decoderen.

Gebruikers met meerdere bedrijven

Eén persoon kan bij meerdere bedrijven horen. Elk bedrijf heeft een eigen token (een eigen claim acc). Om te wisselen:

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

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

Het doel moet een van de available_companies van de aanroeper zijn (teruggegeven bij het inloggen), anders 403 forbidden. De response is een nieuw paar toegangs- en vernieuwingstokens voor het doel; het oude vernieuwingstoken wordt ingetrokken en er wordt een auditgebeurtenis auth.account.swapped geschreven.

Meervoudige authenticatie

MFA op basis van TOTP kan per lid worden ingesteld en per account verplicht worden gemaakt. Staat het aan, dan geeft POST /auth/login een uitdaging terug en wordt de sessie voltooid met POST /auth/mfa/verify. Bij het instellen worden back-upcodes uitgegeven.

Bescherming van het inloggen

• Inlogroutes zijn beperkt tot 10 pogingen per IP-adres per minuut en 5 per e-mailadres per 15 minuten.
• Tien mislukte inlogpogingen blokkeren het e-mailadres voor 30 minuten; de response bevat code: account_locked.
• reCAPTCHA kan per actie worden ingeschakeld (aanmelden, inloggen, wachtwoordherstel); de openbare opstartconfiguratie wordt geleverd via GET /api/v1/captcha.