Vai al contenuto principale
L’autenticazione è una novità. La pagina di accesso ospitata esegue tutti i metodi di questa pagina. Gli endpoint JSON elencati qui servono ai team che creano le proprie schermate di accesso (sign_in_ui: "own").
Abilita un metodo con PUT methods/{name}/ e {"enabled": true} sull’API di gestione dell’autenticazione della tua applicazione, oppure dalla console. La pagina di accesso ospitata mostra solo i metodi che hai abilitato. Ogni chiamata JSON qui sotto inizia con una transaction ottenuta da POST authorize/. La transazione dura 10 minuti. Un accesso riuscito restituisce {code, redirect_uri, state}. Scambia il codice con POST token/ entro 60 secondi (vedi token e JWKS). Invece di un codice, una chiamata di accesso può restituire uno di questi passaggi. Completa il passaggio e riceverai il codice.

​
Password

POST password/ richiede transaction, email e password.
  • Una password deve rispettare il tuo password_min_length (8, 10, 12 o 14 caratteri; 10 per impostazione predefinita). Le password comuni e quelle solo numeriche vengono rifiutate con password_policy. Quando il controllo delle password compromesse è attivo, una password nota come compromessa viene rifiutata con password_breached.
  • Solo chi ha un’email verificata può accedere con una password.
  • Una password errata, un’email sconosciuta, un’email non verificata, un account bloccato e un account a cui è stato impedito l’accesso ricevono tutti la stessa risposta: 400 {"error": "invalid_credentials"}. La tua interfaccia non può capire quale sia stato il motivo, e nemmeno un malintenzionato.

​
Registrazione

La registrazione verifica prima l’email. Chiama POST email/start/ con purpose: "signup", email e password, poi POST email/complete/ con il codice. L’account viene creato con un’email verificata.
  • signup_policy decide chi può registrarsi: anyone, invited (solo con un link di invito) o allowed_domains.
  • Con allow_subaddresses: false (impostazione predefinita), un indirizzo con + nella parte locale viene rifiutato.
  • Quando il tuo branding imposta link ai termini o alla privacy, il modulo di registrazione ospitato chiede alla persona di accettarli.

​
Codice via email

POST email/start/ richiede transaction, purpose (login o signup) e email, e restituisce 202 {challenge, expires_in: 600}. La persona riceve un codice di 6 cifre valido per 10 minuti. POST email/complete/ richiede transaction, purpose, challenge e code. Hai 5 tentativi, poi la persona deve richiedere un nuovo codice. La pagina ospitata offre un nuovo codice dopo 30 secondi. Un codice di accesso per un indirizzo senza account crea un account quando la tua signup_policy lo consente. Questa è la registrazione senza password. La pagina ospitata invia un link di accesso valido per 15 minuti. Il link resta legato alla transazione PKCE originale, quindi funziona solo nel flusso che lo ha avviato. La persona conferma l’accesso nella pagina che si apre con il link. Per i link magici non esiste un endpoint JSON.

​
Codice via telefono

POST phone/start/ richiede transaction, phone e, facoltativamente, channel (sms, predefinito, oppure whatsapp). Il numero viene normalizzato in E.164. Restituisce 202 {challenge, expires_in: 600}. POST phone/complete/ richiede transaction, challenge e il code di 6 cifre. Hai 5 tentativi.
  • I codici via telefono vengono inviati tramite la verifica telefonica di Didit. Abilita il metodo con il workflow_id di un workflow che contiene la verifica telefonica.
  • Un primo accesso con il telefono crea un account solo se signup_policy è anyone.
  • Se l’invio non riesce, la chiamata restituisce 503 {"error": "delivery_unavailable"}.

​
Passkey

Le passkey usano WebAuthn. La parte affidante è l’origine di accesso della tua applicazione. Didit richiede una credenziale rilevabile (chiave residente) e richiede sempre la verifica dell’utente, come un’impronta digitale, il volto o il PIN del dispositivo. Didit non richiede l’attestazione.
  • Una sfida passkey dura 5 minuti.
  • Aggiungere una passkey richiede una sessione creata negli ultimi 5 minuti. In caso contrario la chiamata restituisce 403 {"error": "reauthentication_required"}. Prima devi far accedere di nuovo la persona.
  • Un accesso con passkey conta come autenticazione a più fattori.
  • Dopo la registrazione, la pagina ospitata propone di aggiungere una passkey (passkeys/setup/begin/ e passkeys/setup/complete/).
  • Le app Android registrate nell’applicazione possono usare le stesse passkey.

​
Accesso social

L’accesso con Google, Microsoft, Apple e GitHub usa le credenziali della tua app OAuth, impostate con PUT methods/{provider}/ e credentials: {client_id, client_secret}. Il callback del provider si trova sulla tua origine di accesso. La prima volta che una persona accede con un provider, deve anche dimostrare di essere proprietaria dell’indirizzo email, con un codice (POST social/email/start/ e POST social/email/verify/). Gli accessi successivi con quel provider saltano questo passaggio. GitHub non può dimostrare un accesso recente, quindi non viene offerto quando invii prompt=login o max_age.

​
SSO dell’organizzazione

L’SSO dell’organizzazione permette all’azienda di un cliente di accedere tramite il proprio provider di identità SAML o OIDC. Configuralo per ogni organizzazione cliente in organizations/{id}/sso/ con protocol (saml o oidc), enabled e config.
  • Puoi inviare al team IT del cliente un link di configurazione valido per 7 giorni.
  • I metadati del tuo provider di servizi SAML sono pubblicati in {origin}/sso/saml/metadata/.
  • L’accesso ospitato trova la connessione dal dominio dell’email verificata della persona, oppure da organization=<slug> nell’URL di accesso.

​
Didit ID Wallet

Le persone che hanno già verificato la propria identità con Didit possono accedere con il loro Didit ID Wallet. Questo metodo è sempre attivo. Il verified_identity della sessione contiene poi ciò che la persona ha scelto di condividere.

​
MFA

Il secondo fattore è un’app di autenticazione (TOTP) con codici di recupero, oppure una passkey.
  • mfa_policy decide chi deve usare l’MFA: optional, everyone oppure organization_admins (il valore predefinito). Chi ha registrato un’app di autenticazione deve sempre usarla.
  • Per registrare un’app di autenticazione, chiama POST mfa/enroll/ con una sessione recente (creata entro 5 minuti). La risposta contiene {challenge, uri}; mostra uri come codice QR. Poi invia il primo codice a POST mfa/confirm/. La risposta contiene 10 codici di recupero monouso. Mostrali una sola volta.
  • Durante l’accesso, invia un codice TOTP o un codice di recupero a POST mfa/complete/ con il challenge. Hai a disposizione 5 tentativi. Per usare una passkey, chiama POST mfa/passkey/begin/ e POST mfa/passkey/complete/.
  • I codici usano intervalli di 30 secondi. Un codice già accettato non può essere riutilizzato.
  • I codici via SMS ed email non sono disponibili come secondo fattore.

​
Password dimenticata e reimpostazione

POST password-reset/start/ accetta email e restituisce 202 {"status": "sent", "expires_in": 1800}. La risposta è la stessa indipendentemente dal fatto che l’indirizzo abbia un account. Il link di reimpostazione è valido per 30 minuti. POST password-reset/complete/ accetta token e password e restituisce {"status": "password_changed"}. Inoltre:
  • rimuove un blocco,
  • termina tutte le sessioni quando revoke_on_password_change è attivo (il valore predefinito),
  • invalida gli altri codici e link in sospeso per quella persona.

​
Inviti

Con signup_policy: "invited", possono registrarsi solo le persone invitate. Un link di invito è valido per 7 giorni e apre la pagina ospitata /invite. Prosegui con token e JWKS, oppure leggi protezione dai bot per blocchi e sfide.
Ultima modifica il 7 novembre 2026