Grant or revoke a permission

POST/v1/directory/policies/{policy_id}/permissions

Grants a permission to a policy, or takes it away. List permissions says which you can grant.

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

Path parameters

Parameter Type Description
policy_id string The policy's ID.

Body

Field Type Description
permission string Required. A permission, such as agents:CreateAgent.
granted boolean Required. true grants it, false revokes it.

Returns

200 OK

{
  "id": "7d8e9f0a-1b2c-4d3e-8f4a-5b6c7d8e9f0a",
  "name": "Agent builders",
  "description": "Create and edit agents",
  "kind": "policy",
  "policy_ids": [],
  "role_ids": [
    "5a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d"
  ],
  "account_ids": [],
  "permissions": [
    "agents:CreateAgent",
    "agents:UpdateAgent",
    "agents:RunAgent"
  ],
  "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 That is not a permission, or it isn't offered to your organization.
404 No such resource in your organization.
409 The policy is managed.

Example

curl -X POST https://<company>.yotta.bot/v1/directory/policies/7d8e9f0a-1b2c-4d3e-8f4a-5b6c7d8e9f0a/permissions \
  -H "Authorization: Bearer $YOTTABOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"permission": "agents:RunAgent", "granted": true}'

With yottactl

yottactl org policies set-permission 7d8e9f0a-1b2c-4d3e-8f4a-5b6c7d8e9f0a \
  --set permission=agents:RunAgent \
  --set granted=true