# Passkey-Registrierung starten

`POST /fapi/v1/me/passkeys/registration-options` · wird vom Sign-in-Host der Umgebung aufgerufen

Startet eine WebAuthn-Registrierung für den angemeldeten Benutzer aus dem Konto-Portal und gibt die Optionen zurück, die an `navigator.credentials.create` übergeben werden. Schließen Sie die Registrierung mit [`POST /fapi/v1/me/passkeys`](./register) ab. Die Registrierung ist 5 Minuten gültig, kann nur einmal abgeschlossen werden und nur von der Sitzung, die sie gestartet hat. Erforderlich ist das Cookie `__Host-idp_session` des angemeldeten Benutzers. Fehlt das Cookie, ist es abgelaufen oder widerrufen, gibt der Endpunkt `401 unauthenticated` zurück. Eine First-Party-Anwendung auf einem anderen Origin kann stattdessen ihr Front-API-Zugriffstoken senden (`Authorization: DPoP <token>` mit einem DPoP-Proof; siehe [Front-API-Zugriffstoken](/docs/api/fapi/front-api-token)).

Die Sitzung muss für einen Passkey in den letzten 10 Minuten verifiziert worden sein, für einen Sicherheitsschlüssel in den letzten 5 Minuten. Hat der Benutzer bereits einen zweiten Faktor, muss die Sitzung außerdem mit einem zweiten Faktor (`urn:idp:acr:mfa`) geöffnet worden sein: Ein neuer Passkey kann die Vertrauensstufe der Sitzung, die ihn hinzufügt, nicht erhöhen.

## Anfrage

Header:

| Header | Erforderlich | Beschreibung |
| --- | --- | --- |
| `Idp-Client` | ja | SDK-Kennung. |
| `Origin` | ja | Muss exakt `https://<sign-in host>` sein. |
| `Content-Type` | ja | `application/json`. |

Body:

| Feld | Typ | Erforderlich | Beschreibung |
| --- | --- | --- | --- |
| `role` | string | ja | `passkey`: Anmeldedaten, die eigenständig anmelden (erfordert, dass die Passkey-Anmeldung in der Umgebung aktiviert ist). `security_key`: Anmeldedaten, die nur als zweiter Faktor verwendet werden (erfordert, dass der zweite Faktor Sicherheitsschlüssel aktiviert ist). |

## Antwort

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

Übergeben Sie `options.publicKey` an `PublicKeyCredential.parseCreationOptionsFromJSON` und das Ergebnis an `navigator.credentials.create`. `excludeCredentials` listet die Anmeldedaten des Benutzers für diese vertrauende Partei auf, damit derselbe Authenticator nicht zweimal registriert wird.

## Fehler

| Status | Code | Wann |
| --- | --- | --- |
| 400 | `malformed_request` | Der Body ist kein gültiges JSON. |
| 400 | `unknown_field` | Der Body enthält ein anderes Feld als `role`. |
| 401 | `unauthenticated` | Kein gültiges Sitzungs-Cookie. |
| 401 | `step_up_required` | Die Sitzung ist zu alt oder ein zweiter Faktor ist erforderlich; verifizieren Sie erneut mit `max_age` (und gegebenenfalls `acr_values`) aus dem Header `WWW-Authenticate`. |
| 403 | `origin_not_allowed` | `Origin` fehlt oder ist falsch. |
| 403 | `no_allowed_method` | Die Umgebung erlaubt diese `role` nicht. |
| 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` | `role` fehlt oder ist weder `passkey` noch `security_key`. |
| 422 | `aaguid_not_allowed` | Die Authenticator-Allowlist der Umgebung ist ungültig; die Registrierung ist blockiert, bis sie korrigiert wird. |

## Beispiel

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

## 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. Senden Sie keine besonderen Kategorien personenbezogener Daten (Gesundheit, biometrische Daten, Religion, politische Meinungen, sexuelle Orientierung) in einem Feld.