rpId einer Verbindung für Passkeys ändern

POST /v1/connections/{connection_id}:change-rp-id · Berechtigung connections:write

Verschiebt eine Passkey-Verbindung auf eine neue rpId und startet ein Migrationsfenster. Ein Passkey ist an die rpId gebunden, mit der er registriert wurde. Sobald Nutzer Passkeys haben, ist dies daher der einzige Weg, die rpId zu ändern: Ein PATCH, das settings.rp_id ändert, wird mit 409 rp_id_change_requires_migration abgelehnt.

Während des Fensters können sich Nutzer weiterhin mit Passkeys der bisherigen rpId anmelden, und neue Passkeys werden auf der neuen rpId registriert. Wenn das Fenster endet, oder wenn Sie es mit Migration der rpId abschließen vorzeitig beenden, werden die Passkeys, die noch auf der bisherigen rpId liegen, widerrufen (Grund rp_id_changed). Nutzer, die keine andere Anmeldemethode haben, benötigen dann eine passwortlose Anmeldung per E-Mail oder eine Kontowiederherstellung. In einer Umgebung kann immer nur eine Migration gleichzeitig laufen.

Die rpId der Verbindung, der Migrationsdatensatz, der Verwaltungs-Auditeintrag und das Ereignis passkey_rp_id.migration_started werden gemeinsam geschrieben. Eine benutzerdefinierte Domain, die die rpId ist oder die bisherige rpId einer laufenden Migration, kann nicht gelöscht werden (409 domain_in_use_by_rp_id).

Anfrage

Feld Typ Pflicht Beschreibung
connection_id path ja Passkey-Verbindungs-ID (conn_…).
If-Match header ja Das ETag der Verbindung (siehe Verbindung abrufen).
Idempotency-Key header nein Optionaler Schlüssel, der einen wiederholten Aufruf sicher macht (16-64 Zeichen).
new_rp_id string ja Die neue rpId: der Hostname einer active-benutzerdefinierten Domain der Umgebung (Kleinbuchstaben, IDNA-A-Label) oder eine leere Zeichenkette, damit jeder Anmelde-Host seine eigene rpId verwendet. Höchstens 253 Bytes.
confirm_rp_id string ja new_rp_id erneut eingegeben.
migration_window_days integer nein Wie viele Tage Passkeys der bisherigen rpId weiterhin funktionieren: 30-365, Standard 90. 
{
  "new_rp_id": "login.example.com",
  "confirm_rp_id": "login.example.com",
  "migration_window_days": 90
}

Antwort

200 OK; die Migration und ein ETag-Header mit der neuen Version der Verbindung.

{
  "id": "rpm_01j9xr4a6b8c0d2e4f6g8h0j2k",
  "connection_id": "conn_01j9xp6q0r1s5t7v9w1x3y5z7b",
  "previous_rp_id": null,
  "new_rp_id": "login.example.com",
  "status": "active",
  "started_at": "2026-10-27T10:00:00Z",
  "ends_at": "2027-01-25T10:00:00Z",
  "completed_at": null,
  "revoked_count": null,
  "new_registration_count": null,
  "fallback_enabled_by_migration": false
}
Feld Beschreibung
previous_rp_id, new_rp_id Die rpId vor und nach der Änderung; null bedeutet, dass jeder Anmelde-Host seine eigene rpId ist.
status active, solange das Fenster läuft; completed, wenn es beendet wurde; completed_early, wenn es vorzeitig beendet wurde.
ends_at Wann das Fenster planmäßig endet.
completed_at, revoked_count, new_registration_count Werden beim Abschluss der Migration geschrieben; null, solange sie active ist.
fallback_enabled_by_migration true, wenn für das Fenster eine Ausweichanmeldemethode aktiviert wurde, weil Passkeys der einzige erste Faktor waren.

Fehler

HTTP Code Wann
400 unknown_field Der Body enthält ein unbekanntes Feld.
404 not_found Die Verbindung existiert nicht oder gehört zu einer anderen Umgebung.
409 rp_id_migration_in_progress In dieser Umgebung läuft bereits eine andere rpId-Migration.
412 precondition_failed If-Match stimmt nicht mit der aktuellen Version überein.
422 validation_failed Ein Feld fehlt, ist zu lang oder außerhalb des Bereichs; new_rp_id ist keine active-benutzerdefinierte Domain der Umgebung oder entspricht der aktuellen rpId; confirm_rp_id weicht ab; oder die Verbindung ist keine Passkey-Verbindung (errors[].pointer: /new_rp_id, /confirm_rp_id, /migration_window_days, /connection_id).
428 precondition_required Der Header If-Match fehlt.
401 unauthenticated Die Anmeldedaten fehlen, sind ungültig oder widerrufen.
403 insufficient_permissions Die Anmeldedaten haben nicht die erforderliche Berechtigung.
429 rate_limited Das Rate-Limit wurde überschritten; wiederholen Sie den Aufruf nach dem Zeitraum Retry-After.
503 service_unavailable Eine Abhängigkeit ist vorübergehend nicht verfügbar; wiederholen Sie den Aufruf nach dem Zeitraum Retry-After.

Beispiel

curl -X POST "https://api.eu.keenauth.com/v1/connections/conn_01j9xp6q0r1s5t7v9w1x3y5z7b:change-rp-id" \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H 'If-Match: "3"' \
  -H "Content-Type: application/json" \
  -d '{"new_rp_id":"login.example.com","confirm_rp_id":"login.example.com"}'

keenauth connections change-rp-id conn_01j9xp6q0r1s5t7v9w1x3y5z7b --if-match '"3"' --yes \
  --data '{"new_rp_id":"login.example.com","confirm_rp_id":"login.example.com"}'