API di Autenticazione

L’Authentication API gestisce tutti i flussi di verifica dell’identità: login email/password, signup, refresh dei token, magic link, autenticazione a due fattori e il flusso di autorizzazione OAuth2. Gli endpoint pubblici non richiedono un header Authorization; gli endpoint utente e admin sì.

Email / Password

POST/api/auth/login

Autentica un utente con email e password. Restituisce un access token, refresh token, ID sessione e scadenza del token. Se il tenant o l’applicazione richiede 2FA e l’utente ha configurato il 2FA, la risposta indicherà che è richiesto un secondo fattore prima dell’emissione dei token.

Corpo della richiesta


{
  "email": "[email protected]",
  "password": "segreto123"
}

Risposta di successo (2FA non richiesta)


{
  "ok": true,
  "data": {
    "accessToken": "eyJhbGciOiJSUzI1NiJ9...",
    "refreshToken": "rt_...",
    "expiresIn": 900,
    "sessionId": "sess_abc123",
    "tokenType": "Bearer"
  }
}

Risposta di successo (2FA richiesta)


{
  "ok": true,
  "data": {
    "requiresTwoFactor": true,
    "sessionId": "sess_abc123",
    "availableMethods": ["totp", "sms"]
  }
}

Codici di errore

Codice	HTTP	Descrizione
`INVALID_CREDENTIALS`	401	Email o password errata
`ACCOUNT_LOCKED`	403	Account bloccato per troppi tentativi falliti
`ACCOUNT_DISABLED`	403	Account disabilitato da un amministratore
`RATE_LIMITED`	429	Troppi tentativi di login

POST/api/auth/signup

Registra un nuovo account utente. Il tenant deve avere il signup abilitato. In caso di successo, restituisce la stessa struttura token del login. Se il tenant richiede la verifica email, viene inviata un’email e l’utente non può eseguire il login fino alla verifica.

Corpo della richiesta


{
  "email": "[email protected]",
  "password": "passwordsicura",
  "firstName": "Giovanna",
  "lastName": "Rossi"
}

firstName e lastName sono opzionali. password è obbligatoria a meno che il tenant non sia configurato solo per signup passwordless.

Risposta di successo


{
  "ok": true,
  "data": {
    "accessToken": "eyJhbGciOiJSUzI1NiJ9...",
    "refreshToken": "rt_...",
    "expiresIn": 900,
    "sessionId": "sess_xyz789",
    "tokenType": "Bearer"
  }
}

Codici di errore

Codice	HTTP	Descrizione
`EMAIL_TAKEN`	409	Esiste già un account con questa email
`SIGNUP_DISABLED`	403	Il tenant ha disabilitato il signup pubblico
`WEAK_PASSWORD`	400	La password non soddisfa i requisiti di robustezza
`VALIDATION_ERROR`	400	Il corpo della richiesta non ha superato la validazione dello schema

Endpoint Token (OAuth2)

POST/api/auth/token

Endpoint token OAuth2. Supporta più grant type: Authorization Code (con PKCE), Client Credentials (M2M) e Device Code. La struttura del corpo della richiesta differisce per grant type.

Questo endpoint è l’endpoint token OAuth2 standard referenziato nel documento di discovery OIDC. Accetta corpi della richiesta application/json o application/x-www-form-urlencoded.

Grant: Authorization Code + PKCE

Usato per scambiare un codice di autorizzazione (dal redirect del hosted login) con i token. Il code_verifier è il valore casuale originale da cui è stato derivato il code_challenge.

Corpo della richiesta


{
  "grant_type": "authorization_code",
  "code": "codice_auth_dal_redirect",
  "code_verifier": "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk",
  "redirect_uri": "https://app.tuodominio.com/callback",
  "client_id": "il-tuo-client-id"
}

Risposta di successo


{
  "ok": true,
  "data": {
    "accessToken": "eyJhbGciOiJSUzI1NiJ9...",
    "refreshToken": "rt_...",
    "idToken": "eyJhbGciOiJSUzI1NiJ9...",
    "expiresIn": 900,
    "tokenType": "Bearer"
  }
}

Codici di errore

Codice	HTTP	Descrizione
`CODE_INVALID`	400	Il codice di autorizzazione non esiste o è scaduto
`CODE_USED`	400	Il codice di autorizzazione è già stato scambiato (monouso)
`PKCE_MISMATCH`	400	`SHA256(code_verifier)` non corrisponde alla challenge memorizzata
`REDIRECT_URI_MISMATCH`	400	`redirect_uri` non corrisponde all’URI registrato

Grant: Client Credentials (M2M)

Usato per l’autenticazione machine-to-machine dove non è coinvolto alcun utente. Il client si autentica usando client_id e client_secret.

Corpo della richiesta


{
  "grant_type": "client_credentials",
  "client_id": "m2m-client-id",
  "client_secret": "m2m-client-secret",
  "scope": "read:users manage:roles"
}

Risposta di successo


{
  "ok": true,
  "data": {
    "accessToken": "eyJhbGciOiJSUzI1NiJ9...",
    "expiresIn": 3600,
    "tokenType": "Bearer",
    "scope": "read:users manage:roles"
  }
}

Grant: Device Code (RFC 8628)

Usato per dispositivi che non possono mostrare un browser (CLI, IoT, Smart TV). Prima il dispositivo richiede un device code; l’utente visita poi l’URL di verifica su un dispositivo separato e approva. Il dispositivo effettua il polling finché non viene approvato.

Corpo della richiesta (polling)


{
  "grant_type": "urn:ietf:params:oauth:grant-type:device_code",
  "device_code": "GmRhmhcxhwAzkoEqiMEg_DnyEysNkuNhszIySk9eS",
  "client_id": "il-tuo-client-id"
}

Risposta in attesa (l’utente non ha ancora approvato)


{
  "ok": false,
  "error": {
    "code": "AUTHORIZATION_PENDING",
    "message": "L'utente non ha ancora approvato la richiesta. Continua il polling."
  }
}

Gestione Token

POST/api/auth/refresh

Scambia un refresh token per un nuovo access token e un nuovo refresh token. I refresh token vengono ruotati ad ogni utilizzo — il vecchio refresh token viene immediatamente invalidato.

Corpo della richiesta


{
  "refreshToken": "rt_..."
}

Risposta di successo


{
  "ok": true,
  "data": {
    "accessToken": "eyJhbGciOiJSUzI1NiJ9...",
    "refreshToken": "rt_nuovo...",
    "expiresIn": 900,
    "tokenType": "Bearer"
  }
}

Codici di errore

Codice	HTTP	Descrizione
`REFRESH_TOKEN_INVALID`	401	Il token non esiste o è stato revocato
`REFRESH_TOKEN_EXPIRED`	401	Il token ha superato il tempo di scadenza

POST/api/auth/validateRequires: authenticated user

Valida l’access token corrente e restituisce le informazioni dell’utente autenticato. Questo endpoint è anche l’endpoint UserInfo OIDC.

Richiesta: Nessun corpo richiesto. L’access token viene letto dall’header Authorization: Bearer.

Risposta di successo


{
  "ok": true,
  "data": {
    "valid": true,
    "userId": "usr_abc123",
    "email": "[email protected]",
    "username": "giovanna.rossi",
    "firstName": "Giovanna",
    "lastName": "Rossi",
    "roles": ["viewer", "billing-admin"],
    "tenant": "acme-corp"
  }
}

POST/api/auth/logoutRequires: authenticated user

Invalida la sessione corrente. Il refresh token associato alla sessione viene revocato. L’access token continua ad essere valido fino alla sua scadenza naturale (i JWT non vengono inseriti in blocklist per default — fai affidamento sui tempi di scadenza brevi).

Richiesta: Nessun corpo richiesto.

Risposta di successo


{
  "ok": true,
  "data": { "loggedOut": true }
}

Magic Link (Passwordless)

POST/api/auth/magic-link

Invia un magic link (email di login passwordless) all’indirizzo specificato. Se non esiste un account e allowSignup è abilitato nella configurazione passwordless del tenant, un nuovo account viene creato automaticamente quando il link viene cliccato.

Corpo della richiesta


{
  "email": "[email protected]",
  "redirectUrl": "https://app.tuodominio.com/callback"
}

redirectUrl è opzionale; fa fallback all’URL di redirect predefinito configurato nel tenant.

Risposta di successo


{
  "ok": true,
  "data": { "sent": true }
}

La risposta è sempre { sent: true } indipendentemente dal fatto che l’email esista, per prevenire l’enumerazione degli utenti.

POST/api/auth/magic-link/verify

Verifica un token magic link. Chiamato automaticamente dalla pagina hosted login quando l’utente clicca il link. Restituisce i token in caso di successo.

Corpo della richiesta


{
  "token": "mlnk_..."
}

Risposta di successo


{
  "ok": true,
  "data": {
    "accessToken": "eyJhbGciOiJSUzI1NiJ9...",
    "refreshToken": "rt_...",
    "expiresIn": 900,
    "tokenType": "Bearer"
  }
}

Codici di errore

Codice	HTTP	Descrizione
`MAGIC_LINK_INVALID`	400	Il token è malformato o non esiste
`MAGIC_LINK_EXPIRED`	400	Il token è scaduto (scadenza default: 15 minuti)
`MAGIC_LINK_USED`	400	Il token è già stato consumato (monouso)

Reset Password

POST/api/auth/forgot-password

Avvia un flusso di reset password. Invia un’email con un link di reset all’indirizzo specificato. La risposta è sempre positiva per prevenire l’enumerazione degli utenti.

Corpo della richiesta


{
  "email": "[email protected]"
}

Risposta di successo


{
  "ok": true,
  "data": { "sent": true }
}

Autenticazione a Due Fattori

POST/api/auth/verify-2fa

Verifica un secondo fattore dopo l’autenticazione iniziale con password. Chiama questo endpoint con l’ID sessione restituito dal login (quando requiresTwoFactor: true) e il codice OTP o la risposta WebAuthn. In caso di successo, restituisce access e refresh token completi.

Corpo della richiesta — TOTP


{
  "sessionId": "sess_abc123",
  "code": "123456",
  "method": "totp"
}

Corpo della richiesta — SMS OTP


{
  "sessionId": "sess_abc123",
  "code": "789012",
  "method": "sms"
}

Corpo della richiesta — WebAuthn


{
  "sessionId": "sess_abc123",
  "method": "webauthn",
  "response": { }
}

response è l’oggetto AuthenticatorAssertionResponse dall’API WebAuthn del browser.

Risposta di successo


{
  "ok": true,
  "data": {
    "accessToken": "eyJhbGciOiJSUzI1NiJ9...",
    "refreshToken": "rt_...",
    "expiresIn": 900,
    "tokenType": "Bearer"
  }
}

Codici di errore

Codice	HTTP	Descrizione
`INVALID_OTP`	400	Il codice fornito è errato
`OTP_EXPIRED`	400	Il codice è scaduto
`SESSION_INVALID`	400	L’ID sessione non è valido o è già stato consumato
`WEBAUTHN_FAILED`	400	La verifica dell’assertion WebAuthn è fallita

GET/api/auth/check-2fa-requiredRequires: authenticated user

Controlla se la sessione corrente richiede la verifica 2FA prima che venga concesso l’accesso completo. Utile per proteggere le pagine dopo il login iniziale per assicurarsi che l’utente abbia completato il flusso completo.

Risposta


{
  "ok": true,
  "data": {
    "required": false,
    "verified": true,
    "availableMethods": ["totp", "sms"]
  }
}

Rilevamento SSO

POST/api/auth/sso/detect

Rileva se il dominio email di un utente ha una connessione Enterprise SSO configurata. Usalo per implementare form di login “intelligenti” che reindirizzano automaticamente gli utenti enterprise al loro provider SSO invece di mostrare il campo password.

Corpo della richiesta


{
  "email": "[email protected]"
}

Risposta — SSO disponibile


{
  "ok": true,
  "data": {
    "ssoAvailable": true,
    "provider": "saml",
    "loginUrl": "https://api.altovar.net/api/auth/sso/login/enterprise-alias"
  }
}

Risposta — nessun SSO


{
  "ok": true,
  "data": {
    "ssoAvailable": false,
    "provider": null,
    "loginUrl": null
  }
}

Endpoint di Autorizzazione OAuth2

POST/api/oauth/authorize

Avvia un flusso OAuth2 Authorization Code + PKCE. Questo endpoint crea una sessione e reindirizza l’utente alla pagina hosted login di Auris. Dopo l’autenticazione riuscita, Auris reindirizza al redirect_uri registrato con un codice di autorizzazione.

Questo endpoint viene tipicamente attivato come redirect del browser (GET o form POST) piuttosto che come chiamata fetch. Il metodo SDK loginWithRedirect() gestisce tutto questo automaticamente.

Parametri (query string o corpo della richiesta)

Parametro	Obbligatorio	Descrizione
`response_type`	Sì	Deve essere `"code"`
`client_id`	Sì	Client ID dell’Applicazione
`redirect_uri`	Sì	URL di callback (deve essere registrato)
`state`	Sì	Token CSRF casuale
`code_challenge`	Sì	BASE64URL(SHA256(code_verifier))
`code_challenge_method`	Sì	Deve essere `"S256"`
`scope`	No	Scope separati da spazi (es. `openid profile email`)
`login_hint`	No	Pre-compila il campo email
`screen_hint`	No	`"signup"` per mostrare prima la schermata di registrazione
`locale`	No	Forza un locale specifico (`en`, `it`, `de`, `fr`, `es`)
`prompt`	No	`"login"` per forzare la ri-autenticazione

Redirect in caso di successo


https://app.tuodominio.com/callback?code=codice_auth_xxx&state=state_originale

Redirect in caso di errore


https://app.tuodominio.com/callback?error=access_denied&error_description=Utente+ha+annullato&state=state_originale

Codici di errore (restituiti come parametri di redirect)

Codice	Descrizione
`invalid_request`	Parametro mancante o non valido
`unauthorized_client`	`client_id` non trovato o `redirect_uri` non registrato
`access_denied`	L’utente ha annullato l’autenticazione
`invalid_scope`	Lo scope richiesto non è consentito

Pagine Correlate

OAuth 2.0 e OIDC — Fondamenti del protocollo dietro gli endpoint di autenticazione
I Token Spiegati — Access token, refresh token e ID token in dettaglio
Flusso PKCE — Come funziona lo scambio Authorization Code + PKCE
Guida Hosted Login — Integra il hosted login con la tua applicazione
Magic Link — Autenticazione email passwordless
Social Login — Configura provider di identità di terze parti
Credenziali M2M Client — Autenticazione server-to-server
Impostazioni Autenticazione — Configura MFA, passwordless e social login nella Console