# Resolve a subject conflict

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

Applies an administrator's decision to an open SSO subject conflict (see [List the subject conflicts of a connection](subject-conflicts.md)). Decide only after you have confirmed with the identity provider's administrator who the new subject belongs to.

| `resolution` | Meaning | What KeenAuth does |
|---|---|---|
| `same_person` | The new subject belongs to the same person (for example, the account was re-created in the identity provider). | Replaces the user's old identity on this connection with the new subject. The user signs in with the new subject from the next sign-in. |
| `different_person` | The email address was given to someone else. | Closes the record and links nothing. The new person never gets into the existing account. |

After `different_person`, the next sign-in of the new person opens a new record. To let the new person sign in, change the email address of the existing account, or block or delete that account; the normal sign-in rules then apply.

The identity change, its events and the audit record are written in one transaction. The audit actor is the credential that made the call.

Repeating the same decision returns the record without writing anything. A different decision on a resolved record returns `409 conflict`. Send an `Idempotency-Key` to get the original response back on retries.

## Request

| Field | Type | Required | Description |
|---|---|---|---|
| `connection_id` | path | yes | Connection ID (`conn_…`). |
| `conflict_id` | path | yes | Subject conflict ID (`sscf_…`). |
| `resolution` | body | yes | `same_person` or `different_person`. |

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

## Response

`200 OK` with the resolved record:

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

## Errors

| HTTP | code | When |
|---|---|---|
| 400 | `unknown_field` / `malformed_request` | The body has an unknown field or is not valid JSON. |
| 401 | `unauthenticated` | The credential is missing, invalid or revoked. |
| 403 | `insufficient_permissions` | The credential lacks `users:write`. |
| 403 | `user_not_active` | `same_person`: the user is blocked or being deleted. The record stays open. |
| 404 | `not_found` | The connection or the record does not exist in this environment, the record belongs to another connection, or it has expired. |
| 409 | `conflict` | The record was resolved with the other decision; or, for `same_person`, the connection is not active, the new subject is now linked to another user, or the user's identity limit is reached. The record stays open in the `same_person` cases. |
| 422 | `validation_failed` | `resolution` is missing or not one of the two values (`errors[].pointer` = `/resolution`). |
| 429 | `rate_limited` | The rate limit was exceeded; retry after the `Retry-After` period. |
| 503 | `service_unavailable` | A dependency is temporarily unavailable; retry after the `Retry-After` period. |

## Example

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