# Eine föderierte Identität mit einem Benutzer verknüpfen

`POST /v1/users/{user_id}/identities` · Berechtigung `users:write`

Verknüpft eine föderierte Identität (das externe Subjekt einer Social-, SAML- oder OIDC-Verbindung) mit dem Benutzer, sodass sich der Benutzer über diese Verbindung anmelden kann. `linked_via` ist immer `admin_api`. Die Verbindung muss eine aktivierte Verbindung dieser Umgebung sein, deren Art zu `type` passt. Ist dieselbe Identität bereits mit diesem oder einem anderen Benutzer verknüpft, schlägt die Anfrage mit `409` fehl und der Eigentümer wird nicht offengelegt. Das externe Subjekt sind personenbezogene Daten: Es wird verschlüsselt gespeichert und nie zurückgegeben, und der Verwaltungs-Audit-Eintrag `user.identity_linked` (Akteur: der API-Schlüssel) enthält es nicht. Das Zusammenführen zweier Benutzer (`source_user_id`) ist nicht verfügbar; ein unbekanntes Feld liefert `400 unknown_field`.

## Anfrage

| Parameter | In | Erforderlich | Beschreibung |
|---|---|---|---|
| `user_id` | path | ja | Benutzer-ID mit dem Präfix `usr_`. |

| Feld | Typ | Erforderlich | Beschreibung |
|---|---|---|---|
| `type` | string | ja | `social`, `saml` oder `oidc`; muss zur Verbindung passen (`social` für eine Social-Verbindung, `saml`/`oidc` für eine Unternehmensverbindung derselben Strategie). |
| `connection_id` | string | ja | Verbindungs-ID mit dem Präfix `conn_`. |
| `subject` | string | ja | Externes Subjekt beim Identitätsanbieter (OIDC `sub`, SAML NameID), höchstens 1024 Byte UTF-8. |

## Antwort

`201 Created` mit der neuen Identität in der Struktur, die `GET /v1/users/{user_id}/identities` zurückgibt.

```json
{
  "id": "idn_0a1b2c3d4e5f6g7h8j9k0m1n2r",
  "type": "oidc",
  "connection_id": "conn_0a1b2c3d4e5f6g7h8j9k0m1n2s",
  "provider": null,
  "linked_via": "admin_api",
  "created_at": "2026-01-15T09:30:00Z"
}
```

## Fehler

Jeder Fehler ist ein `application/problem+json`-Body mit einem stabilen `code`.

| HTTP | `code` | Wann |
|---|---|---|
| 400 | `malformed_request`, `unknown_field` | Der Body ist kein gültiges JSON oder enthält ein unbekanntes Feld. |
| 409 | `conflict` | Die Identität ist bereits mit einem Benutzer verknüpft (`errors[]`: `identity_already_linked`) oder der Benutzer hat das Limit für Identitäten pro Benutzer erreicht (`errors[]`: `identity_limit_reached`). |
| 415 | `unsupported_media_type` | Der Body wurde ohne `Content-Type: application/json` gesendet. |
| 422 | `validation_failed` | Ein Feld fehlt oder ist ungültig (`/type`, `/connection_id`, `/subject`), oder die Verbindung ist keine aktivierte Verbindung dieser Umgebung, die zu `type` passt (`errors[]`: `/connection_id`, `connection_unavailable`). |
| 404 | `not_found` | Der Benutzer existiert in dieser Umgebung nicht, wird gerade gelöscht oder die ID ist fehlerhaft. |
| 401 | `unauthenticated` | Der API-Schlüssel fehlt, ist ungültig oder widerrufen. |
| 403 | `insufficient_permissions` | Der Schlüssel hat nicht die Berechtigung `users:write`. |
| 429 | `rate_limited` | Das Rate-Limit wurde überschritten; beachten Sie `Retry-After`. |
| 503 | `service_unavailable` | Eine Abhängigkeit ist vorübergehend nicht verfügbar; versuchen Sie es später erneut. |

## Beispiel

```bash
curl -X POST https://api.eu.keenauth.com/v1/users/usr_0a1b2c3d4e5f6g7h8j9k0m1n2p/identities \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type": "oidc", "connection_id": "conn_0a1b2c3d4e5f6g7h8j9k0m1n2s", "subject": "248289761001"}'
```

## Personenbezogene Daten

Dieser Endpunkt verarbeitet personenbezogene Daten: verknüpfte Identitäten. [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 irgendeinem Feld.