> ## Documentation Index
> Fetch the complete documentation index at: https://docs.base44.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Create workspace group
> This API is in beta. Endpoints, fields, and behavior may still change, so avoid depending on it in production.
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.
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.
## OpenAPI
````yaml /developers/references/app-management/app-management-openapi.json post /api/workspace/groups
openapi: 3.1.0
info:
title: Base44 App Management API
version: 1.0.0
servers:
- url: https://app.base44.com
security:
- PersonalAccessTokenAuth: []
paths:
/api/workspace/groups:
post:
summary: Create workspace group
description: >-
This API is in beta. Endpoints, fields, and behavior may still
change, so avoid depending on it in production.
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.
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.
operationId: create_group_api_workspace_groups_post
parameters:
- name: workspaceId
in: query
required: true
schema:
type: string
minLength: 1
description: >-
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).
title: Workspaceid
description: >-
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).
example: 67e0b12c4d8a3f005b21c9e4
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateGroupRequest'
responses:
'200':
description: The new group.
content:
application/json:
schema:
$ref: '#/components/schemas/WorkspaceGroupSummary'
'400':
description: >-
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':
description: Missing or invalid credentials.
'402':
description: The workspace's plan doesn't include groups.
'403':
description: >-
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':
description: Your workspace requires an unlocked SSO session.
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
'429':
description: Rate limit exceeded.
components:
schemas:
CreateGroupRequest:
properties:
name:
type: string
maxLength: 100
minLength: 1
title: Name
description: >-
Name of the group, up to 100 characters. Must be unique among the
workspace's custom groups, ignoring case.
example: Design team
description:
anyOf:
- type: string
maxLength: 500
- type: 'null'
title: Description
description: Short description of the group's purpose, up to 500 characters.
example: Product designers
role:
anyOf:
- type: string
- type: 'null'
title: Role
description: >-
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.
example: editor
member_emails:
items:
type: string
type: array
maxItems: 200
title: Member Emails
description: Emails of active workspace members to add, up to 200.
example:
- dana@acme.com
- sam@acme.com
type: object
required:
- name
title: CreateGroupRequest
WorkspaceGroupSummary:
properties:
id:
type: string
title: Id
description: ID of the group.
example: 68b4e1d2c9a7f3001e2d4b61
name:
type: string
title: Name
description: Name of the group.
example: Design team
description:
anyOf:
- type: string
- type: 'null'
title: Description
description: Short description of the group, or `null` when it has none.
example: Product designers
source:
type: string
title: Source
description: >-
`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.
example: custom
role:
anyOf:
- type: string
- type: 'null'
title: Role
description: >-
Role every member gets from the group: `admin`, `editor`, `viewer`,
or `no_access`. `null` when the group grants no role.
example: editor
member_count:
type: integer
title: Member Count
description: Number of members.
example: 12
unresolved_count:
type: integer
title: Unresolved Count
description: >-
Members your identity provider sent who don't have a Base44 account
in the workspace yet. Always `0` for a `custom` group.
default: 0
example: 0
type: object
required:
- id
- name
- source
- member_count
title: WorkspaceGroupSummary
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
type: object
required:
- loc
- msg
- type
title: ValidationError
securitySchemes:
PersonalAccessTokenAuth:
type: http
scheme: bearer
description: 'Personal access token, sent as `Authorization: Bearer `.'
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.