# Attributzuordnungen einer Verbindung ersetzen

`PUT /v1/connections/{connection_id}/attribute-mappings` · Berechtigung `connections:write`

Ersetzt die vollständige Attributzuordnungsliste einer Unternehmensverbindung. Die Reihenfolge der Regeln spielt keine Rolle; die Antwort ist nach Ziel sortiert. `If-Match` ist erforderlich: Ohne diesen Header schlägt die Anfrage mit `428` fehl; wurde die Liste seit dem Lesen geändert (oder passt der Wert nicht), schlägt sie mit `412` fehl und es wird nichts geschrieben. Das Senden derselben Liste schreibt nichts. Die Änderung gilt ab der nächsten Anmeldung und macht den letzten bestandenen Verbindungstest nicht ungültig. Der Schreibvorgang wird als `connection.attribute_mappings_replaced` protokolliert (hinzugefügte, entfernte und geänderte Ziele); Attributwerte aus Anmeldungen werden niemals im Audit-Log gespeichert.

## Anfrage

| Feld | Typ | Pflicht | Beschreibung |
|---|---|---|---|
| `connection_id` | Pfad | ja | ID der Unternehmensverbindung (`conn_…`). |
| `If-Match` | Header | ja | Der `ETag` aus dem letzten Lesevorgang. Fehlt: `428`; veraltet: `412`. |
| `attribute_mappings` | Array | ja | Die vollständige neue Liste, höchstens 28 Regeln. |
| `attribute_mappings[].target` | String | ja | `email` (in jeder Liste erforderlich), `given_name`, `family_name`, `name`, `locale`, `zoneinfo`, `phone`, `groups` oder `user_metadata.<key>` (Schlüssel `[a-z0-9_]{1,40}`; registrierte OIDC-Claim-Namen und das Präfix `idp_` sind nicht erlaubt; höchstens 20 Schlüssel). Eine Regel pro Ziel. `app_metadata` kann per Zuordnung nicht geschrieben werden. |
| `attribute_mappings[].source_name` | String | ja | 1–512 Byte, keine Steuer- oder bidirektionalen Zeichen, kein führendes oder nachgestelltes Leerzeichen. |
| `attribute_mappings[].source_name_format` | String \| null | nein | SAML-`NameFormat` (absolute URI). Ein Quellname kann nur mit einem einzigen Format gelesen werden. |
| `attribute_mappings[].overwrite` | String | ja | `always`, `if_empty` oder `never`. |
| `attribute_mappings[].profile` | String | nein | Name der Voreinstellung; ohne Angabe `generic`. |

## Antwort

`200 OK` mit der gespeicherten Liste (siehe [Attributzuordnungen abrufen](get.md)) und dem neuen `ETag`.

## Fehler

| HTTP | code | Wann |
|---|---|---|
| 404 | `not_found` | Die Verbindung existiert in dieser Umgebung nicht oder ist keine Unternehmensverbindung. |
| 409 | `conflict` | Das Protokoll der Verbindung kennt keine Attributzuordnungen (LDAP). |
| 412 | `precondition_failed` | `If-Match` stimmt nicht mit der aktuellen Version überein, oder die Liste wurde gleichzeitig geändert. |
| 422 | `validation_failed` | Eine Regel verletzt die oben genannten Regeln. Jede fehlerhafte Regel ist ein Eintrag in `errors[]`, der auf `/attribute_mappings/<index>/<field>` verweist, oder auf `/attribute_mappings` für Listenregeln (`email_required`, `too_many_metadata_keys`). |
| 428 | `precondition_required` | Der Header `If-Match` fehlt. |
| 400 | `unknown_field` | Der Anfrageninhalt enthält ein unbekanntes Feld. |
| 401 | `unauthenticated` | Das Zugangsdatum fehlt, ist ungültig oder widerrufen. |
| 403 | `insufficient_permissions` | Dem Zugangsdatum fehlt die erforderliche Berechtigung. |
| 429 | `rate_limited` | Das Ratenlimit wurde überschritten; wiederholen Sie die Anfrage nach der Zeit aus `Retry-After`. |
| 503 | `service_unavailable` | Eine Abhängigkeit ist vorübergehend nicht verfügbar; wiederholen Sie die Anfrage nach der Zeit aus `Retry-After`. |

## Beispiel

```bash
curl -X PUT "https://api.eu.keenauth.com/v1/connections/conn_01j9xp6q0r1s5t7v9w1x3y5z7b/attribute-mappings" \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -H 'If-Match: "6f1c…"' \
  -d '{"attribute_mappings":[{"target":"email","source_name":"email","overwrite":"always"},{"target":"user_metadata.department","source_name":"department","overwrite":"if_empty"}]}'
```

```bash
keenauth connections attribute-mappings put conn_01j9xp6q0r1s5t7v9w1x3y5z7b --data @mappings.json --if-match '"6f1c…"'
```