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). 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. 
{ "resolution": "same_person" }

Response

200 OK with the resolved record:

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

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

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