# Risolvi un conflitto di soggetto

`POST /v1/connections/{connection_id}/subject-conflicts/{conflict_id}:resolve` · autorizzazione `users:write`

Applica la decisione di un amministratore a un conflitto di soggetto SSO aperto (vedi [Elenca i conflitti di soggetto di una connessione](subject-conflicts.md)). Decidi solo dopo aver verificato con l'amministratore del provider di identità a chi appartiene il nuovo soggetto.

| `resolution` | Significato | Cosa fa KeenAuth |
|---|---|---|
| `same_person` | Il nuovo soggetto appartiene alla stessa persona (per esempio, l'account è stato ricreato nel provider di identità). | Sostituisce la vecchia identità dell'utente su questa connessione con il nuovo soggetto. L'utente accede con il nuovo soggetto a partire dal successivo accesso. |
| `different_person` | L'indirizzo email è stato assegnato a un'altra persona. | Chiude il record e non collega nulla. La nuova persona non entra mai nell'account esistente. |

Dopo `different_person`, il successivo accesso della nuova persona apre un nuovo record. Per permetterle di accedere, cambia l'indirizzo email dell'account esistente, oppure blocca o elimina quell'account; si applicano poi le normali regole di accesso.

La modifica dell'identità, i relativi eventi e il record di audit vengono scritti in un'unica transazione. L'attore dell'audit è la credenziale che ha effettuato la chiamata.

Ripetere la stessa decisione restituisce il record senza scrivere nulla. Una decisione diversa su un record già risolto restituisce `409 conflict`. Invia un `Idempotency-Key` per ricevere di nuovo la risposta originale nei tentativi successivi.

## Richiesta

| Campo | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| `connection_id` | path | sì | ID della connessione (`conn_…`). |
| `conflict_id` | path | sì | ID del conflitto di soggetto (`sscf_…`). |
| `resolution` | body | sì | `same_person` oppure `different_person`. |

```json
{ "resolution": "same_person" }
```

## Risposta

`200 OK` con il record risolto:

```json
{
  "id": "sscf_01j9xr4a6b8c0d2e4f6g8h0j2k",
  "connection_id": "conn_01j9xp6q0r1s5t7v9w1x3y5z7b",
  "user_id": "usr_01j9xm2n4p6q8r0s2t4v6w8x0y",
  "status": "resolved",
  "resolution": "same_person",
  "created_at": "2026-10-28T10:00:00Z",
  "last_seen_at": "2026-10-28T10:05:00Z",
  "expires_at": "2026-11-27T10:00:00Z",
  "closed_at": "2026-10-28T11:00:00Z"
}
```

## Errori

| HTTP | code | Quando |
|---|---|---|
| 400 | `unknown_field` / `malformed_request` | Il corpo contiene un campo sconosciuto o non è JSON valido. |
| 401 | `unauthenticated` | La credenziale è mancante, non valida o revocata. |
| 403 | `insufficient_permissions` | La credenziale non ha `users:write`. |
| 403 | `user_not_active` | `same_person`: l'utente è bloccato o in fase di eliminazione. Il record resta aperto. |
| 404 | `not_found` | La connessione o il record non esistono in questo ambiente, il record appartiene a un'altra connessione, oppure è scaduto. |
| 409 | `conflict` | Il record è stato risolto con l'altra decisione; oppure, per `same_person`, la connessione non è attiva, il nuovo soggetto è ora collegato a un altro utente, o è stato raggiunto il limite di identità dell'utente. Nei casi `same_person` il record resta aperto. |
| 422 | `validation_failed` | `resolution` manca oppure non è uno dei due valori (`errors[].pointer` = `/resolution`). |
| 429 | `rate_limited` | È stato superato il limite di richieste; riprova dopo il periodo indicato in `Retry-After`. |
| 503 | `service_unavailable` | Una dipendenza non è temporaneamente disponibile; riprova dopo il periodo indicato in `Retry-After`. |

## Esempio

```bash
curl -X POST "https://api.eu.keenauth.com/v1/connections/conn_01j9xp6q0r1s5t7v9w1x3y5z7b/subject-conflicts/sscf_01j9xr4a6b8c0d2e4f6g8h0j2k:resolve" \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"resolution":"different_person"}'
```

```bash
keenauth connections subject-conflicts resolve conn_01j9xp6q0r1s5t7v9w1x3y5z7b sscf_01j9xr4a6b8c0d2e4f6g8h0j2k \
  --resolution different_person --yes
```