---
title: "Update workspace group"
method: PUT
path: "/api/workspace/groups/{group_id}"
---

# Update workspace group

`PUT /api/workspace/groups/{group_id}`

## Request

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

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

Renames a group, changes its description, or changes the role it grants. Send only the fields you want to change.

Set `role` to `null` to clear it, so the group grants no role. Leave `role` out to keep it. A new role on a custom group applies to every member right away.

A group whose `source` is `idp` gets its name and members from your identity provider, so they can't be changed here. Its role and description can still change. An `idp` group grants its role only while the workspace uses identity-provider groups. Otherwise its role is stored but grants nothing. You can't make a change that removes your own admin access.

The response's `unresolved_count` is always `0`. Read the real count from [List workspace groups](/api-reference/list-workspace-groups).

Groups need the Business plan or higher. Below it, this returns a `402`.

This is limited to 60 requests per minute, shared with the other endpoints that change groups or their 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 or admin 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 refused, and workspace API keys aren't accepted.</Note>

## Path parameters

- `group_id` string, required: ID of the group to update. Get it from `id` in [List workspace groups](/api-reference/list-workspace-groups).

## 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).

## Request body

- UpdateGroupRequest
  - `name` string, nullable: New name, up to 100 characters. An identity-provider group's name can't change.
  - `description` string, nullable: New description, up to 500 characters. An empty string clears it.
  - `role` string, nullable: New role: `admin`, `editor`, `viewer`, or `no_access`. Send `null` to clear it so the group grants no role, or leave it out to keep it.

## Response `200`

The updated group.

- WorkspaceGroupSummary
  - `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

- `400`: Another custom group already has this name, you tried to rename an identity-provider group, or the change would remove your own admin access.
- `401`: Missing or invalid credentials.
- `402`: The workspace's plan doesn't include groups.
- `403`: You aren't an owner or admin of the workspace, your token is for a different workspace or is read-only, or your credential can't be used on this endpoint.
- `404`: Group not found in this workspace.
- `409`: Your workspace requires an unlocked SSO session.
- `422`: Validation Error
- `429`: Rate limit exceeded.

## Changes

- **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/:group_id/put.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)