# Démarrer l'enregistrement d'une clé d'accès

`POST /fapi/v1/me/passkeys/registration-options` · appelé depuis l'hôte de connexion de l'environnement

Ouvre un enregistrement WebAuthn pour l'utilisateur authentifié depuis le portail du compte et renvoie les options à transmettre à `navigator.credentials.create`. Terminez-le avec [`POST /fapi/v1/me/passkeys`](./register). L'enregistrement est valide pendant 5 minutes, ne peut être terminé qu'une seule fois, et uniquement par la session qui l'a démarré. Requiert le cookie `__Host-idp_session` de l'utilisateur authentifié ; si le cookie est absent, expiré ou révoqué, renvoie `401 unauthenticated`. Une application de première partie sur une autre origine peut à la place envoyer son jeton d'accès à l'API front (`Authorization: DPoP <token>` avec une preuve DPoP ; voir [Jeton d'accès à l'API front](/docs/api/fapi/front-api-token)).

La session doit avoir été vérifiée au cours des 10 dernières minutes pour une clé d'accès, ou au cours des 5 dernières minutes pour une clé de sécurité. Si l'utilisateur dispose déjà d'un second facteur, la session doit aussi avoir été ouverte avec un second facteur (`urn:idp:acr:mfa`) : une nouvelle clé d'accès ne peut pas élever le niveau d'assurance de la session qui l'ajoute.

## Requête

En-têtes :

| En-tête | Requis | Description |
| --- | --- | --- |
| `Idp-Client` | oui | Identifiant du SDK. |
| `Origin` | oui | Doit être exactement `https://<hôte de connexion>`. |
| `Content-Type` | oui | `application/json`. |

Corps :

| Champ | Type | Requis | Description |
| --- | --- | --- | --- |
| `role` | string | oui | `passkey` : un identifiant qui permet de se connecter seul (nécessite que la connexion par clé d'accès soit activée dans l'environnement). `security_key` : un identifiant utilisé uniquement comme second facteur (nécessite que le second facteur par clé de sécurité soit activé). |

## Réponse

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

Transmettez `options.publicKey` à `PublicKeyCredential.parseCreationOptionsFromJSON`, puis le résultat à `navigator.credentials.create`. `excludeCredentials` liste les identifiants de l'utilisateur pour cette partie de confiance, afin que le même authentificateur ne soit pas enregistré deux fois.

## Erreurs

| Statut | Code | Quand |
| --- | --- | --- |
| 400 | `malformed_request` | Le corps n'est pas un JSON valide. |
| 400 | `unknown_field` | Le corps contient un champ autre que `role`. |
| 401 | `unauthenticated` | Aucun cookie de session valide. |
| 401 | `step_up_required` | La session est trop ancienne ou un second facteur est requis ; vérifiez à nouveau avec `max_age` (et, le cas échéant, `acr_values`) dans l'en-tête `WWW-Authenticate`. |
| 403 | `origin_not_allowed` | `Origin` est absent ou incorrect. |
| 403 | `no_allowed_method` | L'environnement n'autorise pas ce `role`. |
| 409 | `credential_limit_reached` | L'utilisateur a déjà atteint le nombre maximal de clés d'accès et de clés de sécurité. |
| 413 | `payload_too_large` | Le corps est trop volumineux. |
| 415 | `unsupported_media_type` | `Content-Type` n'est pas `application/json`. |
| 422 | `validation_failed` | `role` est absent ou n'est ni `passkey` ni `security_key`. |
| 422 | `aaguid_not_allowed` | La liste d'authentificateurs autorisés de l'environnement est invalide ; l'enregistrement est bloqué jusqu'à correction. |

## Exemple

```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"}'
```

## Données personnelles

Cet endpoint traite des données personnelles : des identifiants. [Données personnelles dans les API KeenAuth](/docs/policies/personal-data) décrit ce qui est stocké, pendant combien de temps et comment elles sont supprimées. N'envoyez pas de catégories particulières de données personnelles (santé, données biométriques, religion, opinions politiques, orientation sexuelle) dans aucun champ.