Avvia una registrazione passkey

POST /fapi/v1/me/passkeys/registration-options · chiamato dall'host di accesso dell'ambiente

Apre una registrazione WebAuthn per l'utente autenticato dal portale dell'account e restituisce le opzioni da passare a navigator.credentials.create. Completala con POST /fapi/v1/me/passkeys. La registrazione è valida per 5 minuti, può essere completata una sola volta e solo dalla sessione che l'ha avviata. Richiede il cookie __Host-idp_session dell'utente autenticato; se il cookie manca, è scaduto o è stato revocato, restituisce 401 unauthenticated. Un'app first-party su un altro origin può invece inviare il proprio access token dell'API front (Authorization: DPoP <token> con una prova DPoP; vedi Access token dell'API front).

La sessione deve essere stata verificata negli ultimi 10 minuti per una passkey, o negli ultimi 5 minuti per una chiave di sicurezza. Se l'utente ha già un secondo fattore, la sessione deve inoltre essere stata aperta con un secondo fattore (urn:idp:acr:mfa): una nuova passkey non può alzare il livello di garanzia della sessione che la aggiunge.

Richiesta

Header:

Header Obbligatorio Descrizione
Idp-Client sì Identificatore dell'SDK.
Origin sì Deve essere esattamente https://<sign-in host>.
Content-Type sì application/json.

Corpo:

Campo Tipo Obbligatorio Descrizione
role string sì passkey: una credenziale che accede da sola (richiede che l'accesso con passkey sia attivo nell'ambiente). security_key: una credenziale usata solo come secondo fattore (richiede che il secondo fattore con chiave di sicurezza sia attivo).

Risposta

200 OK:

{
  "ceremony_id": "CQAAAAAAAAAAAAAAAAAAAA",
  "options": {"publicKey": {"challenge": "…", "rp": {"id": "example.keenauth.app", "name": "Example"}, "user": {"id": "…", "name": "ada@example.org", "displayName": "ada@example.org"}, "pubKeyCredParams": [], "timeout": 300000, "excludeCredentials": [], "authenticatorSelection": {}, "attestation": "none", "extensions": {"credProps": true}}}
}

Passa options.publicKey a PublicKeyCredential.parseCreationOptionsFromJSON e il risultato a navigator.credentials.create. excludeCredentials elenca le credenziali dell'utente per questo relying party, così lo stesso autenticatore non viene registrato due volte.

Errori

Stato Codice Quando
400 malformed_request Il corpo non è JSON valido.
400 unknown_field Il corpo contiene un campo diverso da role.
401 unauthenticated Nessun cookie di sessione valido.
401 step_up_required La sessione è troppo vecchia o è richiesto un secondo fattore; verifica di nuovo con max_age (e, se applicabile, acr_values) nell'header WWW-Authenticate.
403 origin_not_allowed Origin manca o è errato.
403 no_allowed_method L'ambiente non consente questo role.
409 credential_limit_reached L'utente ha già il numero massimo di passkey e chiavi di sicurezza.
413 payload_too_large Il corpo è troppo grande.
415 unsupported_media_type Content-Type non è application/json.
422 validation_failed role manca oppure non è passkey o security_key.
422 aaguid_not_allowed La allowlist degli autenticatori dell'ambiente non è valida; la registrazione è bloccata finché non viene corretta.

Esempio

curl -X POST https://example.keenauth.app/fapi/v1/me/passkeys/registration-options \
  -H "Idp-Client: my-app/1.0.0 (node/22.0.0)" \
  -H "Origin: https://example.keenauth.app" \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d '{"role": "passkey"}'

Dati personali

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