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