scim_users
GET /Users
List users provisioned in the token's organization.
Returns only memberships in the token org. Filters support userName eq "email" and externalId eq "id"; userName comparison is case-insensitive and externalId is case-sensitive. Unsupported attributes/operators or malformed filters return 400 with scimType invalidFilter. Pagination is stable by resource id; startIndex is one-based, count is capped at 200, and count=0 returns only the total count with an empty Resources array.
Operation ID: listScimUsers · Service: gateway-api
Authentication
scimBearer(http (bearer)) — An org-bound SCIM token; session JWTs and project API keys are rejected.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
count | query | no | integer | Requested page size. Negative values are interpreted as zero; the server returns at most 200 resources even for a larger requested count. |
filter | query | no | string | Supported SCIM equality expression; unsupported filters return invalidFilter. |
startIndex | query | no | integer | One-based index; values below 1 are interpreted as 1 (RFC 7644 section 3.4.2.4). |
Pagination
RFC 7644 pagination uses startIndex and count. List responses contain
totalResults, startIndex, itemsPerPage, and Resources.
Responses
| Status | Schema | Description |
|---|---|---|
200 | ScimUserListResponse | Organization-scoped SCIM list. |
400 | ScimError | Invalid request; unsupported filters set scimType to invalidFilter. |
401 | ScimError | Missing, malformed, wrong or revoked organization SCIM token. |
429 | ScimError | Organization SCIM token bucket exceeded. |
default | ScimError | SCIM Error with a status string matching the HTTP status. |
POST /Users
Create or link a user and organization membership.
userName is an email unique within the token org. A pre-existing global user with that email may be linked without revealing other memberships. A pre-existing SCIM membership in this org is a 409 uniqueness conflict, including replay; this endpoint does not use the /v1 idempotency envelope. New memberships receive the token's configured default role (member when omitted at mint). New users carry provisioned_via=scim. externalId round-trips unchanged. Omitted active on creation defaults to true; explicit active=null clears the administrative state and grants no access. The generator preserves omission versus null for this runtime decision. Linking an existing member with a different administrative state (active=false for an active member, or true for a deactivated one) is a 403 unless every permission that member holds is within the token's permission ceiling. Emits scim.user_create.
Operation ID: createScimUser · Service: gateway-api
Authentication
scimBearer(http (bearer)) — An org-bound SCIM token; session JWTs and project API keys are rejected.
Request body
Content-Type: application/scim+json.
Responses
| Status | Schema | Description |
|---|---|---|
201 | ScimUser | Created SCIM user resource. |
400 | ScimError | Invalid request; unsupported filters set scimType to invalidFilter. |
401 | ScimError | Missing, malformed, wrong or revoked organization SCIM token. |
403 | ScimError | Protected owner membership or unauthorized role mutation. |
409 | ScimError | Duplicate userName or group displayName; scimType uniqueness. |
429 | ScimError | Organization SCIM token bucket exceeded. |
default | ScimError | SCIM Error with a status string matching the HTTP status. |
GET /Users/{id}
Get a user resource within the token's organization.
Operation ID: getScimUser · Service: gateway-api
Authentication
scimBearer(http (bearer)) — An org-bound SCIM token; session JWTs and project API keys are rejected.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
id | path | yes | string |
Responses
| Status | Schema | Description |
|---|---|---|
200 | ScimUser | User resource scoped to the token organization. |
401 | ScimError | Missing, malformed, wrong or revoked organization SCIM token. |
404 | ScimError | Resource absent from this org; no cross-org existence disclosure. |
429 | ScimError | Organization SCIM token bucket exceeded. |
default | ScimError | SCIM Error with a status string matching the HTTP status. |
PUT /Users/{id}
Replace a SCIM user's writable attributes.
Resource id and the token org are immutable. active=false soft-deactivates only this org's membership; explicit active=true restores it. Omitted active and explicit active=null both clear the administrative state; an unassigned state grants no access and is returned as active=null. Replacement never reactivates by omission. Omitted optional attributes are cleared; null and [] clear multi-valued attributes. A username conflict returns 409. The last owner cannot be deactivated or cleared; no role or owner grant can be supplied as a user attribute. Changing the administrative state of a member who holds permissions beyond the token's permission ceiling (the minting administrator's) returns 403.
Operation ID: replaceScimUser · Service: gateway-api
Authentication
scimBearer(http (bearer)) — An org-bound SCIM token; session JWTs and project API keys are rejected.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
id | path | yes | string |
Request body
Content-Type: application/scim+json.
Responses
| Status | Schema | Description |
|---|---|---|
200 | ScimUser | User resource scoped to the token organization. |
400 | ScimError | Invalid request; unsupported filters set scimType to invalidFilter. |
401 | ScimError | Missing, malformed, wrong or revoked organization SCIM token. |
403 | ScimError | Protected owner membership or unauthorized role mutation. |
404 | ScimError | Resource absent from this org; no cross-org existence disclosure. |
409 | ScimError | Duplicate userName or group displayName; scimType uniqueness. |
429 | ScimError | Organization SCIM token bucket exceeded. |
default | ScimError | SCIM Error with a status string matching the HTTP status. |
DELETE /Users/{id}
Soft-deactivate this organization's membership.
Equivalent to active=false; no rows are deleted. Repeating deactivation is harmless. Deactivated members remain visible to the org's SCIM token and may be reactivated. A different org's user id returns 404. A member who holds permissions beyond the token's permission ceiling returns 403 and stays active.
Operation ID: deactivateScimUser · Service: gateway-api
Authentication
scimBearer(http (bearer)) — An org-bound SCIM token; session JWTs and project API keys are rejected.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
id | path | yes | string |
Responses
| Status | Schema | Description |
|---|---|---|
204 | — | Membership deactivated; user and audit history retained. |
401 | ScimError | Missing, malformed, wrong or revoked organization SCIM token. |
403 | ScimError | Protected owner membership or unauthorized role mutation. |
404 | ScimError | Resource absent from this org; no cross-org existence disclosure. |
429 | ScimError | Organization SCIM token bucket exceeded. |
default | ScimError | SCIM Error with a status string matching the HTTP status. |
PATCH /Users/{id}
Change membership active state with a SCIM PatchOp.
Supports replace on path active with a boolean value, or a pathless replace with value {active: boolean}. Operation names are case-insensitive per RFC 7644. Attribute paths and pathless supported attribute names are case-insensitive. Null is not a supported active value for this bounded PATCH subset (400); use PUT to clear it. Apply the list atomically. Unsupported operations or paths return 501 SCIM Error and make no mutation; malformed requests return 400. Deactivation emits scim.user_deactivate and takes effect on the next session request; true restores access. Changing the state of a member who holds permissions beyond the token's permission ceiling returns 403. The last-owner invariant remains enforced.
Operation ID: patchScimUser · Service: gateway-api
Authentication
scimBearer(http (bearer)) — An org-bound SCIM token; session JWTs and project API keys are rejected.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
id | path | yes | string |
Request body
Content-Type: application/scim+json.
Responses
| Status | Schema | Description |
|---|---|---|
200 | ScimUser | User resource scoped to the token organization. |
400 | ScimError | Invalid request; unsupported filters set scimType to invalidFilter. |
401 | ScimError | Missing, malformed, wrong or revoked organization SCIM token. |
403 | ScimError | Protected owner membership or unauthorized role mutation. |
404 | ScimError | Resource absent from this org; no cross-org existence disclosure. |
429 | ScimError | Organization SCIM token bucket exceeded. |
501 | ScimError | Unsupported SCIM patch operation or path; nothing was mutated. |
default | ScimError | SCIM Error with a status string matching the HTTP status. |
Errors
SCIM responses use application/scim+json and RFC 7644 Error objects.
The status attribute is a string containing the HTTP status code;
detail describes the failure and scimType may identify its cause.
HTTP 429 responses include Retry-After.
{
"detail": "Unsupported filter",
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:Error"
],
"scimType": "invalidFilter",
"status": "400"
}