Autenticazione

Chiavi API (consigliate per le integrazioni)

Una chiave API è un token di accesso personale legato a un membro del tuo account.

• Creala in Impostazioni → Plugin → Chiavi API RolChat. Il segreto viene mostrato una sola volta; in seguito sono visibili solo i primi dieci caratteri, e RolChat conserva solo un hash SHA-256.
• Formato: rcp_ seguito da 32 byte casuali in base64url, circa 45 caratteri in tutto. Il prefisso rende la chiave riconoscibile nei log e distinta da un token di sessione.
• Scope: scelti da un catalogo fisso di funzionalità al momento della creazione. Una chiave non può mai fare più del membro che l’ha creata: a ogni chiamata si verificano entrambe le condizioni, la funzionalità è negli scope della chiave e il membro la possiede ancora. Se restringi il ruolo del membro, si restringe anche la chiave.
• Durata: le chiavi non scadono da sole. Revoca una chiave dalla pagina del profilo o con DELETE /api/v1/tokens/:id; la revoca ha effetto immediato. Non esiste la rotazione sul posto: revoca e crea una nuova chiave.
• Creazione e revoca vengono scritte nel log di audit.

Inviala come token bearer; non esiste un’intestazione separata per le chiavi API:

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

Le richieste con una chiave API di plugin sono limitate a 300 al minuto.

Sessioni JWT

L’app web e gli SDK mobile accedono con email e password (oppure Google o Apple) e ricevono una coppia di token.

Token	Durata	Note
Access token	15 minuti	RS256, verificato con il JWKS su /.well-known/jwks.json
Refresh token	30 giorni	Ruotato a ogni refresh; il riutilizzo di un token già ruotato revoca l’intera catena

Claim: sub (utente), acc (account), rl (ruolo) e, per i ruoli per sito, sts (siti consentiti).

POST /auth/login, /auth/refresh, /auth/swap-company e /auth/logout sono gli unici endpoint del flusso di autenticazione che non devono riportare l’intestazione X-Account-Id descritta di seguito.

L’intestazione X-Account-Id

Ogni richiesta autenticata, tranne le quattro sopra, deve indicare l’account su cui agisce:

X-Account-Id: <account uuid>

Il server verifica che l’intestazione coincida con il claim acc del token (o con l’account della chiave API). Un’intestazione mancante dà 400 missing_required_header; una discordanza dà 403 account_context_mismatch. L’intestazione esiste perché un bug del client o un token riutilizzato non possano mai leggere in silenzio i dati di un altro tenant: la discordanza viene rifiutata prima dell’esecuzione di qualsiasi query, e ogni riga di log è attribuibile a un account senza decodificare il token.

Utenti con più aziende

Una persona può appartenere a più aziende. Ogni azienda ha il proprio token (con il proprio claim acc). Per cambiare azienda:

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

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

L’azienda di destinazione deve essere tra le available_companies del chiamante (restituite al login), altrimenti si ottiene 403 forbidden. La risposta è una nuova coppia di access token e refresh token limitata all’azienda di destinazione; il vecchio refresh token viene revocato e viene scritto un evento di audit auth.account.swapped.

Autenticazione a più fattori

L’MFA basata su TOTP si può attivare per singolo membro e rendere obbligatoria per account. Quando è attiva, POST /auth/login restituisce una challenge e la sessione si completa con POST /auth/mfa/verify. I codici di backup vengono emessi al momento dell’attivazione.

Protezione dell’accesso

• Le route di accesso sono limitate a 10 tentativi per IP al minuto e a 5 per email ogni 15 minuti.
• Dieci accessi falliti bloccano l’email per 30 minuti; la risposta riporta code: account_locked.
• reCAPTCHA si può attivare per singola azione (registrazione, accesso, reimpostazione password); la configurazione pubblica di bootstrap è servita da GET /api/v1/captcha.