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

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:

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

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