API: Users

User lifecycle contract

Users endpoints expose create, patch, replace, and deactivate semantics. Each update path must preserve deterministic behavior and return repeatable result states.

Core examples

GET /v2/Users?filter=userName eq "alice"
POST /v2/Users  (idempotent client-generated ID)
PATCH /v2/Users/{id}  [{ op: "replace", path: "active", value: false }]

Scale and consistency

Return stable sort ordering when paging to avoid duplicate reads.
Limit filter depth to reduce query planner surprises.
Document conflict and stale-write handling for client replay loops.

SCIM transcript example

GET /v2/Users?filter=userName+eq+%22alice%22&startIndex=1&count=25
HTTP/2 200
{ "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"], "startIndex": 1, "itemsPerPage": 25, "totalResults": 1, "Resources": [ ... ] }

Edge case: PATCH + missing version field
- Status: 409
- Error: versionMismatch
- Operator response: refresh and replay from current etag