Esegui un passaggio di accesso

POST /fapi/v1/transactions/current/steps/{step} · chiamato dall'host di accesso dell'ambiente

Esegue un passaggio della transazione corrente. Questa versione accetta i passaggi identifier e password. Ogni passaggio di credenziali non riuscito restituisce lo stesso 401 invalid_credentials, quindi la risposta non rivela mai se un account esiste. Quando il passaggio della password completa la transazione, vengono impostati i cookie di sessione __Host-idp_session (e, quando serve, __Host-idp_device) e il cookie di transazione viene rimosso.

Richiesta

Intestazioni:

Percorso: step, il nome del passaggio (identifier, password, sso_start).

Al passaggio otp_send, next_steps[].methods elenca i metodi senza password che la policy effettiva consente (email_otp, magic_link); un client offre solo questi.

Corpo (i campi dipendono dal passaggio; next_steps[].fields li elenca):

Risposta

200 OK con la transazione dopo il passaggio. Una transazione completed non ha csrf_token.

Quando l'ambiente richiede un secondo fattore e l'utente non ne ha ancora nessuno, un utente che è ancora nel periodo di tolleranza dell'ambiente mfa.enrollment_grace_days accede comunque e la risposta completed contiene mfa_enrollment: required_by (RFC 3339, la fine della tolleranza, calcolata dal server) e methods (webauthn, totp: i fattori che l'utente può registrare ora, nell'ordine delle schermate). Mostra la data e lascia che l'utente continui; la registrazione si aggiunge nelle impostazioni dell'account. Il campo è assente quando non c'è tolleranza, l'utente rispetta la policy o la registrazione è richiesta subito. Il min_acr di un'applicazione e il acr_values richiesto non vengono mai rinviati dalla tolleranza.

Single Sign-On aziendale (home realm discovery)

Quando il passaggio identifier riceve un indirizzo email il cui dominio appartiene a una connessione aziendale, l'accesso prosegue con quella connessione. Solo la parte dopo @ viene usata per la discovery.

• Una connessione: la transazione passa a federated_redirect e la risposta contiene redirect_url, l'indirizzo di avvio del provider di identità. Naviga alla finestra di primo livello verso quell'indirizzo. L'indirizzo contiene un token monouso: non memorizzarlo né registrarlo.
• Più connessioni: la transazione resta in identifier_pending e la risposta elenca sso_connections (connection_id, display_name, protocol). Mostra display_name come testo e invia la scelta dell'utente con il passaggio sso_start (identifier e connection_id). Una connessione non offerta per il dominio restituisce 422 validation_failed.
• Nessuna connessione, oppure discovery temporaneamente non disponibile: l'accesso normale prosegue, così un'interruzione non blocca gli altri metodi di accesso. sso_start è una scelta esplicita e restituisce invece 503 temporarily_unavailable.

Quando la richiesta di accesso indica un'organizzazione che richiede SSO, la transazione offre solo le connessioni di quell'organizzazione: i passaggi con password e con codice email non sono offerti, e la passkey resta disponibile solo se l'organizzazione ha account di emergenza (break-glass). La creazione della transazione avvia già l'unica connessione (federated_redirect con redirect_url) oppure elenca più connessioni in sso_connections; invia la scelta con sso_start e connection_id soltanto, identifier è facoltativo qui. Con questo requisito la discovery non ripiega su altri metodi: quando l'accesso aziendale non è raggiungibile, il passaggio restituisce 503 temporarily_unavailable. Lo stesso vale quando il dominio email appartiene a un'organizzazione che richiede SSO per i suoi domini verificati.

Dopo il provider di identità, il browser torna a /u/sso/complete sull'host di accesso; la pagina ospitata completa l'accesso.

Collegare l'accesso aziendale a un account esistente

Quando una connessione aziendale non garantisce gli indirizzi email e l'indirizzo che dichiara è già verificato su un account dell'ambiente, l'accesso aziendale non apre una sessione. Il browser torna alla pagina di accesso ospitata con una nuova transazione il cui oggetto contiene account_link: connection_name e, quando la connessione appartiene a un'organizzazione, organization_name. Comunica all'utente che ha già un account e che deve accedervi per collegare la connessione; non nominare mai l'account. In questa transazione sso_start e magic_link non sono offerti, e il passaggio identifier non instrada verso una connessione aziendale.

L'utente accede all'account esistente con i propri metodi; un utente con un secondo fattore registrato viene invitato a usarlo. Il passaggio che completa la transazione non apre alcuna sessione: la connessione viene collegata all'account, e la risposta è una nuova transazione in federated_redirect con redirect_url per la stessa connessione. Naviga alla finestra di primo livello verso quell'indirizzo; l'accesso aziendale ora termina come di consueto. Se l'accesso aziendale non può essere avviato, la nuova transazione è identifier_pending e segue un accesso ordinario.

Completare con un altro account, senza il secondo fattore registrato, o con un accesso più vecchio della richiesta di collegamento non collega nulla e non apre alcuna sessione: 409 transaction_state_conflict. Una richiesta di collegamento scaduta (10 minuti) o già usata restituisce 410 transaction_expired. Una richiesta di collegamento si usa una sola volta, qualunque sia l'esito. Per rifiutare, chiama POST /fapi/v1/transactions/current:cancel.

Policy dell'organizzazione

Quando la richiesta di autorizzazione è vincolata a un'organizzazione, la policy di accesso dell'organizzazione viene verificata di nuovo dopo il primo fattore e subito prima dell'apertura della sessione:

• L'indirizzo IP del client non è nella allowlist dell'organizzazione: 403 ip_not_allowed.
• I fattori della transazione non soddisfano la policy dell'organizzazione (un metodo che l'organizzazione non consente, un fattore mancante, oppure una chiave di sicurezza o passkey fuori dalla allowlist AAGUID dell'organizzazione): 403 no_allowed_method.
• La policy dell'organizzazione non può essere letta: 503 temporarily_unavailable. L'accesso fallisce in modo sicuro e non prosegue mai senza la policy.

Nessuna sessione viene aperta. Un rifiuto al completamento della transazione rimuove il cookie di transazione; un 503 dopo il primo fattore lascia la transazione dov'era, e il passaggio può essere ripetuto. Il corpo dell'errore non nomina mai l'organizzazione, l'utente o l'indirizzo IP.

Transazioni headless vincolate a DPoP

Per una transazione avviata con un'intestazione DPoP, invia una nuova prova dalla stessa chiave (htm POST, htu l'URL del passaggio) invece di Idp-Csrf-Token; nessun cookie viene usato. Il passaggio che completa la transazione restituisce authorization_response una sola volta:

{
  "state": "completed",
  "authorization_response": { "code": "<code>", "state": "<your state>", "iss": "https://example.keenauth.app" },
  "next_steps": [],
  "schema_version": 1,
  "expires_at": "2026-11-02T10:15:00Z"
}

Verifica che state e iss corrispondano, poi scambia il codice presso /oauth2/token con il tuo code_verifier e una prova DPoP dalla stessa chiave. Una prova di un'altra chiave restituisce invalid_grant. Se la richiesta di autorizzazione non può terminare con un codice (serve consenso, termini legali, una scelta dell'organizzazione o un nuovo accesso, oppure l'accesso è negato), il passaggio restituisce 403 authorization_failed e il membro error contiene il codice di errore OAuth; nessun codice viene emesso.

Errori

Esempio

curl -X POST https://example.keenauth.app/fapi/v1/transactions/current/steps/identifier \
  -H "Idp-Client: my-app/1.0.0 (node/22.0.0)" \
  -H "Origin: https://example.keenauth.app" \
  -H "Idp-Csrf-Token: $CSRF_TOKEN" \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d '{"identifier":"jane@example.com"}'

Dati personali

Questo endpoint contiene dati personali: profilo dell'utente finale e credenziali. Dati personali nelle API di KeenAuth descrive cosa viene memorizzato, per quanto tempo viene conservato e come viene cancellato. Non inviare categorie particolari di dati personali (salute, dati biometrici, religione, opinioni politiche, orientamento sessuale) in nessun campo.