Autenticazione

Blu Pantheon supporta tre metodi di autenticazione, pensati per contesti diversi. Tutte le richieste devono viaggiare su HTTPS: le chiamate in chiaro vengono rifiutate a livello di edge.

1. Bearer JWT (sessioni utente)

Usa questo metodo quando l'azione è compiuta per conto di un utente e devi ereditarne ruoli e permessi.

Login

{
  "email": "mario.rossi@acme.it",
  "password": "•••••••••••",
  "tenantSlug": "acme"
}

{
  "type": "success",
  "accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ1c3JfNGE3YjFlOTAi...",
  "refreshToken": "rt_8c1d4f7a2b9e0563a1d8c47f2e9b0355",
  "tokenType": "Bearer",
  "expiresIn": 900,
  "user": {
    "id": "usr_4a7b1e90",
    "email": "mario.rossi@acme.it",
    "roles": ["tenant_admin"]
  }
}

Il campo tenantSlug è obbligatorio solo se l'utente appartiene a più tenant. In sua assenza, quando esistono più appartenenze, la risposta è 409 con codice TENANT_SELECTION_REQUIRED e l'elenco dei tenant disponibili in details.

Uso dell'access token

curl https://api.blupantheon.com/console/v1/sessions \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."

Claim contenuti nel token

L'access token è un JWT firmato con RSA (RS256). La chiave pubblica è pubblicata su https://api.blupantheon.com/identity/v1/.well-known/jwks.json e va usata per la verifica lato tuo.

Payload decodificato di esempio:

{
  "sub": "usr_4a7b1e90",
  "tid": "tnt_2b8e4f11",
  "tslug": "acme",
  "roles": ["tenant_admin"],
  "scope": "identity:users:read identity:users:write console:sessions:read",
  "iss": "https://api.blupantheon.com/identity",
  "iat": 1788515535,
  "exp": 1788516435,
  "jti": "jti_5d0a9b3c"
}

Refresh

{
  "refreshToken": "rt_8c1d4f7a2b9e0563a1d8c47f2e9b0355"
}

{
  "accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "rt_1f6b2e94d7c3a08516ba9e2f7c4d1088",
  "tokenType": "Bearer",
  "expiresIn": 900
}

Il refresh token è a uso singolo. Se lo stesso refresh token viene presentato due volte, l'intera famiglia di token viene revocata e la risposta è 401 con codice REFRESH_TOKEN_REUSED: è il segnale di un possibile furto di credenziali e richiede un nuovo login.

Logout

{
  "refreshToken": "rt_1f6b2e94d7c3a08516ba9e2f7c4d1088",
  "allSessions": false
}

{}

Flusso MFA

Se l'utente ha l'autenticazione a più fattori attiva, il login non restituisce token ma una sfida.

{
  "type": "mfa_required",
  "mfaToken": "mfa_3e7c9a15b2d84f06",
  "methods": ["totp", "email"],
  "expiresIn": 300
}

{
  "mfaToken": "mfa_3e7c9a15b2d84f06",
  "method": "email"
}

{
  "mfaToken": "mfa_3e7c9a15b2d84f06",
  "code": "418206"
}

{
  "type": "success",
  "accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "rt_9b0e4d7a1c62f358",
  "tokenType": "Bearer",
  "expiresIn": 900
}

Il mfaToken scade dopo 5 minuti (MFA_TOKEN_EXPIRED). Dopo 5 codici errati l'account viene bloccato temporaneamente e la risposta è 423 con codice ACCOUNT_LOCKED. I codici di recupero monouso possono essere usati al posto del codice, sullo stesso endpoint, nel campo code.

Per la configurazione lato prodotto vedi Autenticazione e MFA.

2. Chiavi API

Le chiavi API identificano un'applicazione, non una persona. Non scadono per impostazione predefinita e non richiedono refresh: sono la scelta corretta per job schedulati, integrazioni ERP e servizi backend.

Creazione

Formato e prefissi

La chiave è composta da prefisso e da un segreto casuale. Nel database Blu Pantheon conserva solo l'hash SHA-256 del segreto e i primi caratteri in chiaro, usati per identificare la chiave nella Console e nei log di audit. Per questo motivo il valore completo non è recuperabile dopo la creazione.

Uso

curl https://api.blupantheon.com/console/v1/clients?limit=50 \
  -H "Authorization: Bearer bp_live_xxxxxxxxxxxxxxxx"

Scope e permessi

Una chiave non può avere più permessi dell'utente che l'ha creata al momento della creazione. Se i permessi dell'utente vengono ridotti in seguito, la chiave mantiene gli scope assegnati fino alla revisione esplicita: rivedi le chiavi attive a ogni cambio di ruolo rilevante.

Quando una chiave chiama un endpoint fuori dai propri scope la risposta è 403 con codice INSUFFICIENT_PERMISSIONS e l'elenco degli scope mancanti in details.

Rotazione

Consigliamo una rotazione almeno semestrale e una rotazione immediata dopo ogni sospetto di esposizione o dopo l'uscita di una persona con accesso al secret manager.

Revoca

{
  "id": "key_6d3f0a82",
  "name": "erp-sync-produzione",
  "status": "revoked",
  "revokedAt": "2026-09-04T10:32:15.482Z"
}

Dopo la revoca ogni chiamata con quella chiave riceve 401 con codice API_KEY_REVOKED.

3. HMAC servizio-a-servizio

Usato per la comunicazione tra servizi interni e per i partner che richiedono garanzie di integrità oltre alla riservatezza del canale TLS. Ogni consumatore riceve un keyId pubblico e un segreto condiviso.

Header richiesti

Stringa da firmare

Gli elementi vengono concatenati con il carattere di ritorno a capo \n, nell'ordine seguente:

<METODO>\n
<PATH_CON_QUERY>\n
<X-BP-TIMESTAMP>\n
<X-BP-NONCE>\n
<SHA256_HEX_DEL_BODY>

Esempio concreto per POST /billing/v1/usage con body {"tenantId":"tnt_2b8e4f11","units":42}:

POST
/billing/v1/usage
1788515535
n_7c2a94f0e13b
3f8a1c9e2b7d0546a83f1c9b0e7d2a45f8c31b9e0d7a24f6c8b135e0a97d4f26

Implementazione in Node.js:

import { createHash, createHmac, randomBytes } from 'node:crypto';

export function signRequest(
  method: string,
  pathWithQuery: string,
  body: string,
  keyId: string,
  secret: string,
): Record<string, string> {
  const timestamp = Math.floor(Date.now() / 1000).toString();
  const nonce = `n_${randomBytes(6).toString('hex')}`;
  const bodyHash = createHash('sha256').update(body, 'utf8').digest('hex');

  const canonical = [method.toUpperCase(), pathWithQuery, timestamp, nonce, bodyHash].join('\n');
  const signature = createHmac('sha256', secret).update(canonical, 'utf8').digest('hex');

  return {
    'X-BP-Key-Id': keyId,
    'X-BP-Timestamp': timestamp,
    'X-BP-Nonce': nonce,
    'X-BP-Signature': `t=${timestamp},v1=${signature}`,
    'Content-Type': 'application/json',
  };
}

Il body va firmato byte per byte esattamente come viene trasmesso: non riserializzare il JSON dopo la firma, perché un diverso ordinamento delle chiavi o una spaziatura differente invalidano l'hash.

Lo stesso schema di firma è usato in direzione opposta per i webhook in uscita: vedi Riferimento webhook e Firma HMAC.

Errori di autenticazione più frequenti

Il catalogo completo è in Errori.