Einen Passkey registrieren

POST /fapi/v1/me/passkeys · wird vom Anmelde-Host der Umgebung aufgerufen

Schließt eine Registrierung ab, die mit POST /fapi/v1/me/passkeys/registration-options gestartet wurde: Prüft die Antwort des Browsers, speichert den Passkey oder Sicherheitsschlüssel und gibt ihn zurück. Der Benutzer erhält eine Sicherheits-E-Mail über die neue Anmeldemethode; diese E-Mail kann nicht deaktiviert werden. Erforderlich ist das Cookie __Host-idp_session des authentifizierten Benutzers. Fehlt das Cookie, ist es abgelaufen oder widerrufen, wird 401 unauthenticated zurückgegeben. Eine First-Party-Anwendung auf einem anderen Ursprung kann stattdessen ihr API-Zugriffstoken für das Frontend senden (Authorization: DPoP <token> mit einem DPoP-Nachweis; siehe Frontend-API-Zugriffstoken).

Für die Sitzung gelten dieselben Regeln wie beim Startaufruf: in den letzten 10 Minuten verifiziert und mit einem zweiten Faktor geöffnet, falls der Benutzer einen hat.

Anfrage

Header:

Header Pflicht Beschreibung
Idp-Client ja SDK-Kennung.
Origin ja Muss genau https://<Anmelde-Host> sein.
Content-Type ja application/json.

Body:

Feld Typ Pflicht Beschreibung
ceremony_id string ja Die ceremony_id des Startaufrufs.
credential object ja Das Ergebnis von navigator.credentials.create als JSON (PublicKeyCredential.toJSON()), maximal 16 KiB.

Antwort

201 Created, der neue Authenticator:

{
  "id": "cred_01j9zzzzzzzzzzzzzzzzzzzzzz",
  "type": "passkey",
  "label": "iCloud Keychain",
  "status": "active",
  "synced": true,
  "created_at": "2026-10-12T09:00:00Z",
  "last_used_at": null
}

Fehler

Eine abgelehnte Registrierung zählt nicht als fehlgeschlagener Versuch; starten Sie eine neue Registrierung.

Status Code Wann
400 malformed_request Der Body ist kein gültiges JSON.
400 unknown_field Der Body enthält ein anderes Feld als ceremony_id und credential.
401 unauthenticated Kein gültiges Sitzungs-Cookie.
401 step_up_required Die Sitzung ist zu alt oder ein zweiter Faktor ist erforderlich; verifizieren Sie sich erneut mit den Werten im Header WWW-Authenticate.
403 origin_not_allowed Origin fehlt oder ist falsch.
409 credential_already_registered Dieser Authenticator ist in der Umgebung bereits registriert.
409 credential_limit_reached Der Benutzer hat bereits die maximale Anzahl an Passkeys und Sicherheitsschlüsseln.
413 payload_too_large Der Body ist zu groß.
415 unsupported_media_type Content-Type ist nicht application/json.
422 validation_failed /ceremony_id: Die Registrierung ist unbekannt, abgelaufen, bereits verwendet oder gehört zu einer anderen Sitzung. /credential: Die Antwort fehlt oder wird nicht verifiziert.
422 device_bound_passkey_required Die Umgebung akzeptiert nur Passkeys, die auf einem Gerät bleiben.
422 aaguid_not_allowed Die Umgebung erlaubt dieses Authenticator-Modell nicht.
422 attestation_untrusted Die Umgebung verlangt eine vertrauenswürdige Attestierung, und diese ist nicht vertrauenswürdig.

Beispiel

curl -X POST https://example.keenauth.app/fapi/v1/me/passkeys \
  -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 '{"ceremony_id": "CQAAAAAAAAAAAAAAAAAAAA", "credential": {"id": "…", "rawId": "…", "type": "public-key", "response": {"clientDataJSON": "…", "attestationObject": "…"}}}'

Personenbezogene Daten

Dieser Endpunkt verarbeitet personenbezogene Daten: Anmeldedaten. Personenbezogene Daten in den KeenAuth-APIs beschreibt, was gespeichert wird, wie lange es aufbewahrt wird und wie es gelöscht wird. Übermitteln Sie in keinem Feld besondere Kategorien personenbezogener Daten (Gesundheit, biometrische Daten, Religion, politische Meinungen, sexuelle Orientierung).