Create a policy

POST/v1/directory/policies

Makes an empty policy. Grant it permissions, then put it in a role.

Permission: identity:CreatePolicy. 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": "7d8e9f0a-1b2c-4d3e-8f4a-5b6c7d8e9f0a",
  "name": "Agent builders",
  "description": "Create and edit agents",
  "kind": "policy",
  "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 policy already has that name.

Example

curl -X POST https://<company>.yotta.bot/v1/directory/policies \
  -H "Authorization: Bearer $YOTTABOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Agent builders", "description": "Create and edit agents"}'

With yottactl

yottactl org policies create \
  --set name=Agent builders \
  --set description=Create and edit agents