# 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`](./register). 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](/docs/api/fapi/front-api-token)).

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`:

```json
{
  "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

```bash
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](/docs/policies/personal-data) 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).