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.

{
  "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

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