List roles

GET/v1/directory/roles

Lists your organization's roles: the policies each holds and the accounts it is on. Managed roles come with your organization and can't be changed.

Permission: identity:ListRoles

Returns

200 OK

{
  "roles": [
    {
      "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"
    }
  ]
}

Example

curl https://<company>.yotta.bot/v1/directory/roles \
  -H "Authorization: Bearer $YOTTABOT_TOKEN"

With yottactl

yottactl org roles list