Skip to content

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 ​

StatusCodeDetail
400limit must be a positive integerInvalid Request
401authentication failedUnauthorized
403insufficient_permissionsForbidden
404the requested resource was not foundNot Found
500authentication service unavailableInternal 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) ​

FieldTypeRequired
namestringYes
team_idstringYes
json
{
  "name": "backend",
  "team_id": "01J8Z3TEAM000000000000001"
}

Responses ​

  • 200 — Successful response
json
{
  "id": "01J8Z3GROUP000000000000001",
  "name": "backend",
  "team_id": "01J8Z3TEAM000000000000001"
}

Errors ​

StatusCodeDetail
400request body must be valid JSONInvalid Request
401authentication failedUnauthorized
403insufficient_permissionsForbidden
404the requested resource was not foundNot Found
409the resource already existsConflict
500authentication service unavailableInternal 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 ​

ParameterDescription
idPath parameter.

Responses ​

  • 204 — No Content

Errors ​

StatusCodeDetail
401authentication failedUnauthorized
403insufficient_permissionsForbidden
404the requested resource was not foundNot Found
500authentication service unavailableInternal 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 ​

ParameterDescription
idPath parameter.

Responses ​

  • 200 — Successful response
json
{
  "id": "01J8Z3GROUP000000000000001",
  "name": "backend",
  "team_id": "01J8Z3TEAM000000000000001"
}

Errors ​

StatusCodeDetail
401authentication failedUnauthorized
403insufficient_permissionsForbidden
404the requested resource was not foundNot Found
500authentication service unavailableInternal 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 ​

ParameterDescription
idPath parameter.

Request body (application/json) ​

FieldTypeRequired
namestringNo
team_idstringNo
json
{
  "name": "platform-backend"
}

Responses ​

  • 200 — Successful response
json
{
  "id": "01J8Z3GROUP000000000000001",
  "name": "platform-backend",
  "team_id": "01J8Z3TEAM000000000000001"
}

Errors ​

StatusCodeDetail
400request body must be valid JSONInvalid Request
401authentication failedUnauthorized
403insufficient_permissionsForbidden
404the requested resource was not foundNot Found
500authentication service unavailableInternal 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 ​

ParameterDescription
idPath parameter.

Request body (application/json) ​

FieldTypeRequired
expires_atstring (date-time)No
user_idstringYes
json
{
  "user_id": "01J8Z3USER000000000000001"
}

Responses ​

  • 204 — No Content

Errors ​

StatusCodeDetail
400request body must be valid JSONInvalid Request
401authentication failedUnauthorized
403insufficient_permissionsForbidden
404the requested resource was not foundNot Found
500authentication service unavailableInternal 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 ​

ParameterDescription
idPath 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 ​

StatusCodeDetail
400limit must be a positive integerInvalid Request
401authentication failedUnauthorized
403insufficient_permissionsForbidden
404the requested resource was not foundNot Found
500authentication service unavailableInternal 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 ​

ParameterDescription
idPath parameter.

Request body (application/json) ​

FieldTypeRequired
expires_atstring (date-time)No
user_idstringYes
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 ​

StatusCodeDetail
400request body must be valid JSONInvalid Request
401authentication failedUnauthorized
403insufficient_permissionsForbidden; Step-up Required
403step_up_requiredForbidden; Step-up Required
404the requested resource was not foundNot Found
500authentication service unavailableInternal 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 ​

ParameterDescription
idPath parameter.

Request body (application/json) ​

FieldTypeRequired
user_idsarray<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 ​

StatusCodeDetail
400request body must be valid JSONInvalid Request
401authentication failedUnauthorized
403insufficient_permissionsForbidden; Step-up Required
403step_up_requiredForbidden; Step-up Required
404the requested resource was not foundNot Found
422a maximum of 500 user_ids is allowedToo Many Items
500authentication service unavailableInternal 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 ​

ParameterDescription
idPath parameter.
userIDPath parameter.

Responses ​

  • 204 — No Content

Errors ​

StatusCodeDetail
401authentication failedUnauthorized
403insufficient_permissionsForbidden
404the requested resource was not foundNot Found
500authentication service unavailableInternal 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 ​

ParameterDescription
idPath parameter.
userIDPath parameter.

Responses ​

  • 200 — Successful response
json
{
  "expires_at": "2026-02-01T00:00:00Z",
  "group_id": "01J8Z3GROUP000000000000001",
  "team_id": "01J8Z3TEAM000000000000001",
  "user_id": "01J8Z3USER000000000000001"
}

Errors ​

StatusCodeDetail
401authentication failedUnauthorized
403insufficient_permissionsForbidden
404the requested resource was not foundNot Found
500authentication service unavailableInternal Server Error