# List the subject conflicts of a connection

`GET /v1/connections/{connection_id}/subject-conflicts` · permission `users:read`

Lists the SSO subject conflicts of an enterprise (SAML or OIDC) connection, newest first.

A subject conflict is recorded when the identity provider sends a **new subject** with the verified email address of a user who is already linked to the same connection under a different subject. This happens, for example, when a former employee's mailbox is given to a new employee. KeenAuth does not link the new subject automatically: the sign-in is refused with `sso_subject_conflict` and a record is opened for an administrator to [resolve](resolve-subject-conflict.md).

- While a record is open, more sign-ins with the same subject update that record instead of opening a new one.
- An open record expires 30 days after it was opened.
- Records never contain the external subject or the email address.

The permission is `users:read` because a record concerns a user account; resolving it needs `users:write`.

## Request

| Field | Type | Required | Description |
|---|---|---|---|
| `connection_id` | path | yes | Connection ID (`conn_…`). |
| `limit` | query | no | Page size, 1–100 (default 20). |
| `after` / `before` | query | no | Cursor from `list_metadata`. A cursor works only for the connection that produced it. |
| `order` | query | no | `desc` (default) or `asc`, by creation time. |

## Response

`200 OK`:

```json
{
  "data": [
    {
      "id": "sscf_01j9xr4a6b8c0d2e4f6g8h0j2k",
      "connection_id": "conn_01j9xp6q0r1s5t7v9w1x3y5z7b",
      "user_id": "usr_01j9xm2n4p6q8r0s2t4v6w8x0y",
      "status": "open",
      "resolution": null,
      "created_at": "2026-10-28T10:00:00Z",
      "last_seen_at": "2026-10-28T10:05:00Z",
      "expires_at": "2026-11-27T10:00:00Z",
      "closed_at": null
    }
  ],
  "list_metadata": { "before": null, "after": null }
}
```

| Field | Description |
|---|---|
| `user_id` | The user who owns the verified email address and is already linked to this connection under another subject. |
| `status` | `open` (waiting for a decision), `resolved` or `expired` (closed 30 days after it was opened, without a decision). |
| `resolution` | `same_person` or `different_person`; set only when `status` is `resolved`. |
| `last_seen_at` | The latest sign-in attempt with the new subject. |
| `closed_at` | When the record was resolved or expired; `null` while it is open. An expired record can also show `null`. |

## Errors

| HTTP | code | When |
|---|---|---|
| 400 | `invalid_cursor` | The cursor is malformed or belongs to another connection or query. |
| 401 | `unauthenticated` | The credential is missing, invalid or revoked. |
| 403 | `insufficient_permissions` | The credential lacks `users:read`. |
| 404 | `not_found` | The connection does not exist in this environment. |
| 422 | `validation_failed` | A query parameter is invalid (for example `limit` above 100). |
| 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 "https://api.eu.keenauth.com/v1/connections/conn_01j9xp6q0r1s5t7v9w1x3y5z7b/subject-conflicts?limit=20" \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY"
```

```bash
keenauth connections subject-conflicts list conn_01j9xp6q0r1s5t7v9w1x3y5z7b --limit 20
```