Collega un'identità federata a un utente

POST /v1/users/{user_id}/identities · autorizzazione users:write

Collega un'identità federata (il soggetto esterno di una connessione social, SAML o OIDC) all'utente, così l'utente può accedere con quella connessione. linked_via è sempre admin_api. La connessione deve essere una connessione abilitata di questo ambiente il cui tipo corrisponde a type. Se la stessa identità è già collegata a questo o a un altro utente, la richiesta fallisce con 409 e il proprietario non viene rivelato. Il soggetto esterno è un dato personale: viene memorizzato cifrato e non viene mai restituito, e il record di audit di gestione user.identity_linked (attore: la chiave API) non lo contiene. L'unione di due utenti (source_user_id) non è disponibile; un campo sconosciuto restituisce 400 unknown_field.

Richiesta

Parametro In Obbligatorio Descrizione
user_id path sì Id utente, con prefisso usr_.
Campo Tipo Obbligatorio Descrizione
type string sì social, saml o oidc; deve corrispondere alla connessione (social per una connessione social, saml/oidc per una connessione enterprise della stessa strategia).
connection_id string sì Id connessione, con prefisso conn_.
subject string sì Soggetto esterno presso il provider di identità (OIDC sub, SAML NameID), al massimo 1024 byte di UTF-8.

Risposta

201 Created con la nuova identità, nella forma restituita da GET /v1/users/{user_id}/identities.

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

Errori

Ogni errore è un corpo application/problem+json con un code stabile.

HTTP code Quando
400 malformed_request, unknown_field Il corpo non è JSON valido o contiene un campo sconosciuto.
409 conflict L'identità è già collegata a un utente (errors[]: identity_already_linked), oppure l'utente ha raggiunto il limite di identità per utente (errors[]: identity_limit_reached).
415 unsupported_media_type Il corpo è stato inviato senza Content-Type: application/json.
422 validation_failed Un campo manca o non è valido (/type, /connection_id, /subject), oppure la connessione non è una connessione abilitata di questo ambiente corrispondente a type (errors[]: /connection_id, connection_unavailable).
404 not_found L'utente non esiste in questo ambiente, è in fase di eliminazione, oppure l'id è malformato.
401 unauthenticated La chiave API è mancante, non valida o revocata.
403 insufficient_permissions La chiave non ha l'autorizzazione users:write.
429 rate_limited È stato superato il limite di frequenza; rispetta Retry-After.
503 service_unavailable Una dipendenza non è temporaneamente disponibile; riprova più tardi.

Esempio

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

Dati personali

Questo endpoint contiene dati personali: identità collegate. Dati personali nelle API di KeenAuth descrive cosa viene memorizzato, per quanto tempo viene conservato e come viene eliminato. Non inviare categorie particolari di dati personali (salute, dati biometrici, religione, opinioni politiche, orientamento sessuale) in nessun campo.