scim_groups
GET /Groups
List groups in the token's organization.
Optional filters support displayName eq "name" and externalId eq "id". Unsupported filters return 400 invalidFilter. Results are ordered by id; pagination has the same one-based count semantics as Users.
Operation ID: listScimGroups · 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 | ScimGroupListResponse | Organization-scoped SCIM group 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 /Groups
Create a group and apply its configured role mapping.
Every member must belong to this org. Nested groups are unsupported. A group maps by displayName to exactly one admin-configured non-owner role; absent a mapping, it grants no permission. Adding a member to a mapped group assigns that org-wide role and emits role.assign plus scim.group_sync. Existing conflicting mapped groups are resolved by last-applied assignment, never permission cardinality, and emit scim.group_conflict. Duplicate displayName returns 409 uniqueness. A change that would replace the role of a member who holds permissions beyond the token's permission ceiling returns 403.
Operation ID: createScimGroup · 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 | ScimGroup | Created SCIM group 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. |
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. |
GET /Groups/{id}
Get a group within the token's organization.
Operation ID: getScimGroup · 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 | ScimGroup | Group 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 /Groups/{id}
Replace a group's writable attributes and membership set.
Resolve all member IDs within this org before any mutation. Omitted members means an empty set. Removed members revert to their latest remaining mapped-group assignment, or their role before group assignment. A displayName change reconciles the old and new mapping atomically. Conflicting assignments use last-applied order and emit scim.group_conflict. A change that would replace the role of a member who holds permissions beyond the token's permission ceiling returns 403.
Operation ID: replaceScimGroup · 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 | ScimGroup | Group 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. |
PATCH /Groups/{id}
Add or remove group members with SCIM PatchOp.
Supports add on path members with an array of {value: user_id}, and remove on members[value eq "user_id"] or remove on path members with a member array. Removing path members without a value removes all members. Operation names and attribute paths are case-insensitive. Unsupported operations or paths return 501 and perform no mutation. Apply the whole operation list atomically in request order, validating all member IDs against this org. Removal restores the previous remaining assignment or pre-group role; addition to conflicting mapped groups uses the last-applied assignment and emits scim.group_conflict, role.assign and scim.group_sync. A change that would replace the role of a member who holds permissions beyond the token's permission ceiling returns 403.
Operation ID: patchScimGroup · 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 | ScimGroup | Group 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"
}