---
title: "List workspace groups"
method: GET
path: "/api/workspace/groups"
---

# List workspace groups

`GET /api/workspace/groups`

## Request

- Base URL: `https://app.base44.com`
- URL: `https://app.base44.com/api/workspace/groups`
- Auth: HTTP bearer

<Info>This API is in beta. Endpoints, fields, and behavior may still change, so avoid depending on it in production.</Info>

Returns every group in a workspace, oldest first, with how many members each has. The list isn't paginated.

Every member of a group gets the group's `role`, and a member of several groups gets the highest of their roles. A group whose `role` is `no_access` blocks members who get their role only from it. An `idp` group grants its role only while the workspace uses identity-provider groups. Otherwise its role is stored but grants nothing.

This is limited to 120 requests per minute, shared with [List group members](/api-reference/list-group-members). A signed-in session has its own limit, and every personal access token for the workspace shares one. Some workspaces have a different limit.

<Note>Call this as an owner, admin, or editor of the workspace, with a personal access token for that workspace sent as a Bearer token, or from a signed-in session. A read-only token is accepted, but workspace API keys aren't.</Note>

## Query parameters

- `workspaceId` string, required: ID of the workspace. With a personal access token, use the token's workspace. Get it from `organization_id` in [Get app](/api-reference/get-app).

## Response `200`

The workspace's groups.

- WorkspaceGroupListResponse
  - `groups` WorkspaceGroupSummary[], required: Every group in the workspace, oldest first.
    - `id` string, required: ID of the group.
    - `name` string, required: Name of the group.
    - `description` string, nullable: Short description of the group, or `null` when it has none.
    - `source` string, required: `custom` for a group created in Base44, or `idp` for one your identity provider sends through SCIM. An `idp` group's name and members come from the identity provider.
    - `role` string, nullable: Role every member gets from the group: `admin`, `editor`, `viewer`, or `no_access`. `null` when the group grants no role.
    - `member_count` integer, required: Number of members.
    - `unresolved_count` integer: Members your identity provider sent who don't have a Base44 account in the workspace yet. Always `0` for a `custom` group.

## Other responses

- `401`: Missing or invalid credentials.
- `403`: You aren't an owner, admin, or editor of the workspace, your token is for a different workspace, or your credential can't be used on this endpoint.
- `409`: Your workspace requires an unlocked SSO session.
- `422`: Validation Error
- `429`: Rate limit exceeded.

## Changes

- **2026-10-13** `32455e516133`: 2 info
  - the security scope `read_only` was added to the endpoint's security scheme `PersonalAccessTokenAuth`
  - the security scope `full_access` was removed from the endpoint's security scheme `PersonalAccessTokenAuth`
- **2026-10-11** `80287813ab84`: 1 info
  - the endpoint scheme security `PersonalAccessTokenAuth` was added to the API
- **2026-10-05** `8a09a50ea8c9`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/base44/apis/base44-app-management-api/changes/api/workspace/groups/get.md)

---

[API](https://skmtc.dev/base44/apis/base44-app-management-api.md) - [All operations](https://skmtc.dev/base44/apis/base44-app-management-api/llms.txt) - [OpenAPI document](https://skmtc.dev/base44/apis/base44-app-management-api/revisions/c534f09cf314?raw)