Verbindung aktualisieren

PATCH /v1/connections/{connection_id} · Berechtigung connections:write

Aktualisiert eine Verbindung per JSON-Merge-Patch (application/merge-patch+json, RFC 7396). If-Match ist erforderlich. key, type, strategy und org_id können nicht geändert werden. Ein Patch, der nichts ändert, schreibt nichts und behält die Version bei. Einstellungen dürfen keine Geheimnisse enthalten.

Anfrage

Feld Typ Pflichtfeld Beschreibung
connection_id string ja Verbindungskennung (conn_…).
If-Match header ja Der ETag der Verbindung, wie zuletzt gelesen. Fehlt er: 428; ist er veraltet: 412.
key string nein Kann nicht geändert werden; derselbe Wert wird akzeptiert.
type string nein Kann nicht geändert werden.
strategy string nein Kann nicht geändert werden.
name string nein 1–128 Zeichen.
display_name string | null nein null entfernt den Wert.
status string nein active oder inactive.
org_id string | null nein Kann nicht geändert werden; derselbe Wert wird akzeptiert.
allowed_email_domains array of strings | null nein Ersetzt die Liste; null oder [] entfernt sie. Gleiche Regeln wie beim Erstellen; bei einer Organisationsverbindung werden nur neu hinzugefügte Domains gegen die verifizierten Domains der Organisation geprüft.
allow_external_domains boolean nein Nur enterprise.
jit_mode string nein create, create_and_update oder off. Nur enterprise.
email_trust boolean nein Nur enterprise. Das Aktivieren für eine Organisationsverbindung erfordert eine nicht leere allowed_email_domains, in der jede Domain eine verifizierte Domain der Organisation ist.
default_role_ids array of strings | null nein Ersetzt die Liste; null oder [] entfernt sie. Gleiche Regeln wie beim Erstellen; geprüft werden nur neu hinzugefügte Rollen. Eine bereits enthaltene Rolle, die später gelöscht wurde, blockiert das Update daher nicht (sie wird bei der Anmeldung übersprungen).
trust_idp_mfa boolean nein Nur enterprise.
settings object | null nein Wird rekursiv zusammengeführt (RFC 7396); ein null-Mitglied löscht diesen Schlüssel; null entfernt alle Einstellungen. Keine Geheimnisse.

Antwort

200 OK mit der aktualisierten Verbindung und dem neuen ETag.

{
  "id": "conn_0k3v8m1q2x9dz4h7s5t6w0y1ab",
  "key": "google",
  "type": "social",
  "strategy": "google",
  "name": "Google",
  "display_name": "Sign in with Google",
  "status": "active",
  "org_id": null,
  "allowed_email_domains": [],
  "allow_external_domains": false,
  "jit_mode": null,
  "email_trust": null,
  "default_role_ids": [],
  "trust_idp_mfa": null,
  "allow_idp_initiated": null,
  "idp_initiated_default_application_id": null,
  "idp_initiated_allowed_application_ids": [],
  "settings": {},
  "created_at": "2026-10-05T09:30:00.123456Z",
  "updated_at": "2026-10-05T09:30:00.123456Z"
}

Passkey-Einstellungen

Bei type: "passkey" akzeptiert das Objekt settings nur die unten aufgeführten Schlüssel. Jeder andere Schlüssel, ein falscher Typ oder ein Wert außerhalb des zulässigen Bereichs wird mit 422 validation_failed und einem errors[].pointer wie /settings/max_credentials_per_user abgelehnt. Ein null-Wert bedeutet den Standardwert. Strukturfehler werden vor Planfehlern gemeldet.

Schlüssel Typ Hinweise
rp_id string Fehlt der Wert, ist er null oder leer, ist jeder Anmelde-Host seine eigene rpId. Andernfalls der Hostname einer active benutzerdefinierten Domain der Umgebung (klein geschrieben, IDNA-A-Label); jeder andere Wert ergibt 422 validation_failed (/settings/rp_id). Sobald die Umgebung Passkeys hat, ändern Sie ihn mit Passkey-rpId ändern.
rp_name string Bis zu 128 Zeichen.
passkey_first_factor_enabled, security_key_second_factor_enabled boolean Standard true.
user_verification string preferred (Standard) oder required.
max_credentials_per_user integer 1–20, Standard 20; Bruchzahlen werden abgelehnt.
require_device_bound_passkeys boolean Planabhängig: true erfordert Startup.
attestation_required boolean Planabhängig: true erfordert Enterprise.
aaguid_allowlist, aaguid_blocklist array of UUID strings Höchstens 500 eindeutige Einträge je Liste (Fehler verweisen auf /settings/<key>/<index>). Planabhängig: Eine nicht leere Liste erfordert Enterprise.
related_origins array of strings Origins der Form https://host[:port]. Planabhängig: Eine nicht leere Liste erfordert Enterprise.
passkey_enrollment_prompt string off oder after_login (Standard).

Das Schreiben eines vom Standard abweichenden Werts eines planabhängigen Schlüssels schlägt mit 403 plan_feature_unavailable fehl, mit den Mitgliedern feature und required_plan. Solange die Planberechtigungen nicht verfügbar sind, können diese Schlüssel in keiner Umgebung gesetzt werden; ein Standardwert (false, [], null) oder das Entfernen des Schlüssels ist immer erlaubt. Ist die Funktion verfügbar, muss jeder Eintrag in related_origins eine aktive, verifizierte benutzerdefinierte Domain der Umgebung sein, andernfalls schlägt die Anfrage mit 422 related_origin_not_verified fehl. Die Einstellungen werden erst nach Anwendung des Merge-Patch validiert, und nur dann, wenn settings Teil des Patches ist.

Fehler

HTTP Code Wann
400 unknown_field Der Patch enthält ein unbekanntes oder schreibgeschütztes Feld.
404 not_found Die Verbindung existiert nicht oder gehört zu einer anderen Umgebung.
409 connection_test_required Der Patch setzt eine enterprise-Verbindung auf active oder fügt einer allowed_email_domains einer active-Verbindung eine Domain hinzu, ohne dass die resultierende Konfiguration in den letzten 24 Stunden erfolgreich getestet wurde (siehe Verbindung aktivieren); es wird nichts geschrieben. Das Entfernen von Domains wird nicht geprüft.
409 rp_id_change_requires_migration Der Patch ändert settings.rp_id einer Passkey-Verbindung, obwohl die Umgebung Passkeys hat, die dann nicht mehr funktionieren würden; verwenden Sie Passkey-rpId ändern. Es wird nichts geschrieben.
412 precondition_failed If-Match stimmt nicht mit der aktuellen Version überein.
415 unsupported_media_type Der Inhaltstyp ist nicht application/merge-patch+json.
422 validation_failed Ein Wert ist ungültig oder ein unveränderliches Feld wurde geändert (code: immutable).
422 related_origin_not_verified Ein zugehöriger Origin ist keine verifizierte benutzerdefinierte Domain der Umgebung.
403 plan_feature_unavailable Der Plan enthält eine von Ihnen gesetzte Einstellung nicht (Mitglieder feature, required_plan), zum Beispiel attestation_required.
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 Ratenlimit wurde überschritten; wiederholen Sie die Anfrage nach der Zeitspanne Retry-After.
503 service_unavailable Eine Abhängigkeit ist vorübergehend nicht verfügbar (zum Beispiel konnte die Passkey-Prüfung einer rp_id-Änderung nicht ausgeführt werden, daher wird nichts geschrieben); wiederholen Sie die Anfrage nach der Zeitspanne Retry-After.

Beispiel

curl -X PATCH https://api.eu.keenauth.com/v1/connections/conn_0k3v8m1q2x9dz4h7s5t6w0y1ab \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Content-Type: application/merge-patch+json" \
  -H 'If-Match: "1"' \
  -d '{"display_name":"Sign in with Google"}'