Create a role
POST/v1/directory/roles
Makes an empty role. Add policies to it, put it on accounts, then assign it to people or groups.
Permission: identity:CreateRole. 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": "5a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
"name": "Developers",
"description": "Build and run agents",
"kind": "role",
"policy_ids": [],
"role_ids": [],
"account_ids": [],
"permissions": [],
"managed": false,
"builtin": "",
"role": "",
"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 |
A role already has that name. |
Example
curl -X POST https://<company>.yotta.bot/v1/directory/roles \
-H "Authorization: Bearer $YOTTABOT_TOKEN" \
-H "Content-Type: application/json" \
-d '{"name": "Developers", "description": "Build and run agents"}'With yottactl
yottactl org roles create \
--set name=Developers \
--set description=Build and run agents