Create a group

POST/v1/directory/groups

Makes a group. Give it a role with Create a role assignment, and everyone in it has that role.

Permission: identity:CreateGroup. Changes need a sign-in that used a second factor.

Body

Field Type Description
name string Required. Up to 128 characters.
description string Up to 1,000 characters.

Returns

201 Created

{
  "id": "3c5e8a90-1d2b-4e6f-8a7c-9b0d1e2f3a4b",
  "name": "Engineering",
  "description": "Everyone who ships code",
  "members": [],
  "created_at": "2026-11-19T09:00:00Z",
  "updated_at": "2026-11-19T09:00:00Z"
}

Errors

Besides the errors every call can return:

Status When
400 A missing name, or one too long.
409 Another group has that name.

Example

curl -X POST https://<company>.yotta.bot/v1/directory/groups \
  -H "Authorization: Bearer $YOTTABOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Engineering", "description": "Everyone who ships code"}'

With yottactl

yottactl org groups create \
  --set name=Engineering \
  --set description=Everyone who ships code