Appearance
Groups API Reference
GET /groups/
List groups in a team
Lists groups for one required team_id, ordered by ascending group ID. See REST pagination for the shared collection contract.
Required permission — iam:groups:any (or iam:groups:team scoped to the target team)
Responses
- 200 — Successful response
json
{
"items": [
{
"id": "01J8Z3GROUP000000000000001",
"name": "backend",
"team_id": "01J8Z3TEAM000000000000001"
}
],
"next_cursor": ""
}Errors
| Status | Code | Detail |
|---|---|---|
| 400 | limit must be a positive integer | Invalid Request |
| 401 | authentication failed | Unauthorized |
| 403 | insufficient_permissions | Forbidden |
| 404 | the requested resource was not found | Not Found |
| 500 | authentication service unavailable | Internal Server Error |
POST /groups/
Create a group
Use to create a team-scoped group that can receive memberships and role bindings.
Required permission — iam:groups:any (or iam:groups:team scoped to the target team)
Request body (application/json)
| Field | Type | Required |
|---|---|---|
| name | string | Yes |
| team_id | string | Yes |
json
{
"name": "backend",
"team_id": "01J8Z3TEAM000000000000001"
}Responses
- 200 — Successful response
json
{
"id": "01J8Z3GROUP000000000000001",
"name": "backend",
"team_id": "01J8Z3TEAM000000000000001"
}Errors
| Status | Code | Detail |
|---|---|---|
| 400 | request body must be valid JSON | Invalid Request |
| 401 | authentication failed | Unauthorized |
| 403 | insufficient_permissions | Forbidden |
| 404 | the requested resource was not found | Not Found |
| 409 | the resource already exists | Conflict |
| 500 | authentication service unavailable | Internal Server Error |
DELETE /groups/{id}
Delete a group
Use to remove a group and its memberships. Affected users' permission versions are invalidated.
Required permission — iam:groups:any (or iam:groups:team scoped to the target team)
Path parameters
| Parameter | Description |
|---|---|
| id | Path parameter. |
Responses
- 204 — No Content
Errors
| Status | Code | Detail |
|---|---|---|
| 401 | authentication failed | Unauthorized |
| 403 | insufficient_permissions | Forbidden |
| 404 | the requested resource was not found | Not Found |
| 500 | authentication service unavailable | Internal Server Error |
GET /groups/{id}
Get a group
Use to retrieve one group by ULID, including its owning team ID.
Required permission — iam:groups:any (or iam:groups:team scoped to the target team)
Path parameters
| Parameter | Description |
|---|---|
| id | Path parameter. |
Responses
- 200 — Successful response
json
{
"id": "01J8Z3GROUP000000000000001",
"name": "backend",
"team_id": "01J8Z3TEAM000000000000001"
}Errors
| Status | Code | Detail |
|---|---|---|
| 401 | authentication failed | Unauthorized |
| 403 | insufficient_permissions | Forbidden |
| 404 | the requested resource was not found | Not Found |
| 500 | authentication service unavailable | Internal Server Error |
PATCH /groups/{id}
Update a group
Use to rename a group or move it to another team. At least one of team_id and name is required; memberships are updated when the team changes.
Required permission — iam:groups:any (or iam:groups:team scoped to the target team)
Path parameters
| Parameter | Description |
|---|---|
| id | Path parameter. |
Request body (application/json)
| Field | Type | Required |
|---|---|---|
| name | string | No |
| team_id | string | No |
json
{
"name": "platform-backend"
}Responses
- 200 — Successful response
json
{
"id": "01J8Z3GROUP000000000000001",
"name": "platform-backend",
"team_id": "01J8Z3TEAM000000000000001"
}Errors
| Status | Code | Detail |
|---|---|---|
| 400 | request body must be valid JSON | Invalid Request |
| 401 | authentication failed | Unauthorized |
| 403 | insufficient_permissions | Forbidden |
| 404 | the requested resource was not found | Not Found |
| 500 | authentication service unavailable | Internal Server Error |
DELETE /groups/{id}/members
Remove a group member by request body
Use to remove a membership when the client has the group ID but sends the user ID as JSON. The path variant with userID is equivalent and is preferred for idempotent URL-based clients.
Required permission — iam:groups:any (or iam:groups:team scoped to the target team)
Path parameters
| Parameter | Description |
|---|---|
| id | Path parameter. |
Request body (application/json)
| Field | Type | Required |
|---|---|---|
| expires_at | string (date-time) | No |
| user_id | string | Yes |
json
{
"user_id": "01J8Z3USER000000000000001"
}Responses
- 204 — No Content
Errors
| Status | Code | Detail |
|---|---|---|
| 400 | request body must be valid JSON | Invalid Request |
| 401 | authentication failed | Unauthorized |
| 403 | insufficient_permissions | Forbidden |
| 404 | the requested resource was not found | Not Found |
| 500 | authentication service unavailable | Internal Server Error |
GET /groups/{id}/members
List group members
Lists membership records for the path group in ascending user_id order. The cursor key is the user ID. See REST collection pagination for the shared collection contract.
Required permission — iam:groups:any (or iam:groups:team scoped to the target team) Requires iam:groups:any or an applicable iam:groups:team grant for the group's active owning team; reads do not require step-up authentication.
Path parameters
| Parameter | Description |
|---|---|
| id | Path parameter. |
Responses
- 200 — Successful response
json
{
"items": [
{
"expires_at": "2026-02-01T00:00:00Z",
"group_id": "01J8Z3GROUP000000000000001",
"team_id": "01J8Z3TEAM000000000000001",
"user_id": "01J8Z3USER000000000000001"
}
],
"next_cursor": ""
}Errors
| Status | Code | Detail |
|---|---|---|
| 400 | limit must be a positive integer | Invalid Request |
| 401 | authentication failed | Unauthorized |
| 403 | insufficient_permissions | Forbidden |
| 404 | the requested resource was not found | Not Found |
| 500 | authentication service unavailable | Internal Server Error |
PUT /groups/{id}/members
Add or replace a group membership
Use to add a user to a group or update that membership's expiry. The operation is idempotent and returns the complete membership record.
Required permission — iam:groups:any (or iam:groups:team scoped to the target team) Requires a user bearer with positive auth_time or step_up_time no older than ten minutes; timestamps up to 30 seconds in the future are accepted. Otherwise returns 403 step_up_required.
Path parameters
| Parameter | Description |
|---|---|
| id | Path parameter. |
Request body (application/json)
| Field | Type | Required |
|---|---|---|
| expires_at | string (date-time) | No |
| user_id | string | Yes |
json
{
"expires_at": "2026-02-01T00:00:00Z",
"user_id": "01J8Z3USER000000000000001"
}Responses
- 200 — Successful response
json
{
"expires_at": "2026-02-01T00:00:00Z",
"group_id": "01J8Z3GROUP000000000000001",
"team_id": "01J8Z3TEAM000000000000001",
"user_id": "01J8Z3USER000000000000001"
}Errors
| Status | Code | Detail |
|---|---|---|
| 400 | request body must be valid JSON | Invalid Request |
| 401 | authentication failed | Unauthorized |
| 403 | insufficient_permissions | Forbidden; Step-up Required |
| 403 | step_up_required | Forbidden; Step-up Required |
| 404 | the requested resource was not found | Not Found |
| 500 | authentication service unavailable | Internal Server Error |
POST /groups/{id}/members/batch
Add group members in a batch
Use to bulk-populate a group. Up to 500 user IDs are processed independently; duplicate rows report already_member and unknown users report not_found.
Required permission — iam:groups:any (or iam:groups:team scoped to the target team) Requires a user bearer with positive auth_time or step_up_time no older than ten minutes; timestamps up to 30 seconds in the future are accepted. Otherwise returns 403 step_up_required.
Path parameters
| Parameter | Description |
|---|---|
| id | Path parameter. |
Request body (application/json)
| Field | Type | Required |
|---|---|---|
| user_ids | array<string> | No |
json
{
"user_ids": [
"01J8Z3USER000000000000001",
"01J8Z3USER000000000000002"
]
}Responses
- 200 — Successful response
json
{
"results": [
{
"id": "01J8Z3USER000000000000001",
"ok": true
},
{
"error": "already_member",
"id": "01J8Z3USER000000000000002",
"ok": false
}
]
}Errors
| Status | Code | Detail |
|---|---|---|
| 400 | request body must be valid JSON | Invalid Request |
| 401 | authentication failed | Unauthorized |
| 403 | insufficient_permissions | Forbidden; Step-up Required |
| 403 | step_up_required | Forbidden; Step-up Required |
| 404 | the requested resource was not found | Not Found |
| 422 | a maximum of 500 user_ids is allowed | Too Many Items |
| 500 | authentication service unavailable | Internal Server Error |
DELETE /groups/{id}/members/{userID}
Remove a group member
Use to remove a membership by group and user ULIDs. Unknown group, user, or membership returns a generic not-found problem.
Required permission — iam:groups:any (or iam:groups:team scoped to the target team)
Path parameters
| Parameter | Description |
|---|---|
| id | Path parameter. |
| userID | Path parameter. |
Responses
- 204 — No Content
Errors
| Status | Code | Detail |
|---|---|---|
| 401 | authentication failed | Unauthorized |
| 403 | insufficient_permissions | Forbidden |
| 404 | the requested resource was not found | Not Found |
| 500 | authentication service unavailable | Internal Server Error |
GET /groups/{id}/members/{userID}
Get a group membership
Use to retrieve one membership by group and user IDs, including its expiry when present. An unknown group, user, or membership returns the same generic not-found response.
Required permission — iam:groups:any (or iam:groups:team scoped to the target team) Requires iam:groups:any or an applicable iam:groups:team grant for the group's active owning team; reads do not require step-up authentication.
Path parameters
| Parameter | Description |
|---|---|
| id | Path parameter. |
| userID | Path parameter. |
Responses
- 200 — Successful response
json
{
"expires_at": "2026-02-01T00:00:00Z",
"group_id": "01J8Z3GROUP000000000000001",
"team_id": "01J8Z3TEAM000000000000001",
"user_id": "01J8Z3USER000000000000001"
}Errors
| Status | Code | Detail |
|---|---|---|
| 401 | authentication failed | Unauthorized |
| 403 | insufficient_permissions | Forbidden |
| 404 | the requested resource was not found | Not Found |
| 500 | authentication service unavailable | Internal Server Error |