Skip to main content
GET
List Groups

Authentication and permissions

Token requirements: User-based token (OAuth) or Organization-scoped API key or Workspace-scoped API key. Send a bearer access token for one of these identities. The permissions and resource restrictions below also apply.
Permissions joined by + are all required; or separates alternatives. Full-access keys still cannot call endpoints marked unsupported. Workspace keys must allow every workspace checked by the request. OAuth access depends on the user’s roles and resource access.
  • Read groups: Group visibility rules still apply.
  • Read groups through a workspace: Supply team_id for a workspace the key allows. List returns groups configured for that workspace. A lookup by group UUID returns any group the key’s workspaces can see; a scoped ID resolves only among groups configured for team_id. The key must hold groups:manage; a full-access workspace key cannot.

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Query Parameters

pageSize
integer<int32>

Maximum number of results to return. Default is 100, maximum is 10000.

pageToken
string

Token for pagination. Leave empty for the first request.

userId
string

Filter to the groups this user is a member of. Each returned group still carries its full user_ids roster, not just this user.

teamId
string

Configuration-workspace namespace, not manager ACL. Unset lists org-visible groups.

groupIds
string[]

Resolve only these group UUIDs and workspace-scoped portable IDs. Requires team_id, and cannot be combined with user_id or page_token.

scopedIds
string[]

Workspace-scoped portable IDs to resolve; like group_ids, requires team_id.

omitMembers
boolean

Omit the user roster when only group identity and configuration are needed.

Response

200 - application/json

Success

data
Group · object[]

The list of groups.

nextPageToken
string | null

Token for retrieving the next page of results. Empty if no more results.