Create Group

BETA

This endpoint is in beta and may change in future releases.

POST/workspace/{workspaceId}/groups

Creates a new user group in a workspace with optional workspace-level permissions and granular permissions for apps and datasources.

Path Parameters

workspaceIdstringrequired

The unique identifier of the workspace.

Request Body

namestringrequired

Name of the group.

permissionsobjectoptional

Workspace-level permissions for the group (e.g. appCreate, appDelete).

granularPermissionsarrayoptional

List of granular permission rules scoped to specific apps or datasources.

Error Responses

400

name fails format constraints (length, invalid chars, reserved keyword, or role name collision).

400

workspaceId not found or no admin user exists in the workspace.

400

A resource in granularPermissions[].resources not found.

401

Missing or invalid Authorization: Basic token.

409

A group with the same name already exists in the workspace.

451

EXTERNAL_API license not active on the instance.

Request

curl -X POST "https://{your-domain}/api/ext/workspace/{workspaceId}/groups" -H "Authorization: Basic <access_token>" -H "Content-Type: application/json" -d '{
"name": "Platform Engineers",
"permissions": {
  "appCreate": true,
  "appDelete": false
},
"granularPermissions": [
  {
    "type": "app",
    "applyToAll": false,
    "resources": [
      "app-uuid-1"
    ],
    "permissions": {
      "canEdit": true,
      "hideFromDashboard": false,
      "environments": [
        "production"
      ]
    }
  }
]
}'

Response — 201

{"message": "Group created successfully."}