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. 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).

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 :

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

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 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.