# 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`.

```json
{
  "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](change-rp-id.md). |
| `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](change-rp-id.md). 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

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