---
title: "Create workspace group"
method: POST
path: "/api/workspace/groups"
---

# Create workspace group

`POST /api/workspace/groups`

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

Creates a custom group in a workspace, optionally with a role and its first members.

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. Leave `role` out for a group that grants no role.

Only active members of the workspace can join a group. Pending invitees, guests, and the workspace owner can't. To add someone who isn't a member yet, invite them with [Invite workspace member](/api-reference/invite-workspace-member) and pass `group_id`. If any address in `member_emails` can't be added, nothing is created.

Group names are unique within a workspace, ignoring case, so retrying a create that succeeded returns a `400`. You can't make a change that removes your own admin access.

The response's `unresolved_count` is always `0`.

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>

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

- CreateGroupRequest
  - `name` string, required — Name of the group, up to 100 characters. Must be unique among the workspace's custom groups, ignoring case.
  - `description` string, nullable — Short description of the group's purpose, up to 500 characters.
  - `role` string, nullable — Role every member gets: `admin`, `editor`, `viewer`, or `no_access` to block members who get their role only from this group. Leave it out, or send `null`, for a group that grants no role.
  - `member_emails` string[] — Emails of active workspace members to add, up to 200.

## Response `200`

The new 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` — A custom group with this name already exists, an address in `member_emails` isn't an active workspace member, 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.
- `409` — Your workspace requires an unlocked SSO session.
- `422` — Validation Error
- `429` — Rate limit exceeded.

## Changes

- **2026-10-05** `8a09a50ea8c9` — 1 info
  - endpoint added

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

---

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