Add a policy to a role

PUT/v1/directory/roles/{role_id}/policies/{policy_id}

Puts a policy in a role. Everyone holding the role gets the policy's permissions.

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

Path parameters

Parameter Type Description
role_id string The role's ID.
policy_id string The policy's ID.

Returns

200 OK

{
  "id": "5a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
  "name": "Developers",
  "description": "Build and run agents",
  "kind": "role",
  "policy_ids": [
    "7d8e9f0a-1b2c-4d3e-8f4a-5b6c7d8e9f0a"
  ],
  "role_ids": [],
  "account_ids": [
    100000000123
  ],
  "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
404 No such resource in your organization.
409 The role is managed.

Example

curl -X PUT https://<company>.yotta.bot/v1/directory/roles/5a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d/policies/7d8e9f0a-1b2c-4d3e-8f4a-5b6c7d8e9f0a \
  -H "Authorization: Bearer $YOTTABOT_TOKEN"

With yottactl

yottactl org roles add-policy 5a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d 7d8e9f0a-1b2c-4d3e-8f4a-5b6c7d8e9f0a