RBAC and roles

Saaya enforces two layers of role-based access control. System roles govern who can administer Saaya itself; organization roles govern who can do what inside a workspace. Permissions are fine-grained and live in code as enums.

System roles

• SUPER_ADMIN, Saaya staff only; emergency org-level operations.
• USER, every authenticated human; the default.

Organization roles

• OWNER, everything ADMIN can do, plus the organization-level actions reserved to ownership.
• ADMIN, everything MEMBER can do, plus inviting, removing, and re-roling members.
• MEMBER, everything VIEWER can do, plus creating and editing agents and knowledge bases.
• VIEWER, read-only, including listing the members of the organization.

Fine-grained permissions

Every endpoint declares the permission it requires, and a role is a bundle of those permissions. The four built-in roles are strictly nested: each one is the role below it plus more. You can list the full permission set, and the role-to-permission matrix, over the API.

If none of the four built-in roles is the right shape, compose your own from the same permission set. Custom roles are created with permission ids, so read the permission list first and pick from it.

curl https://api.saaya.ai/api/v1/roles/permissions -H "X-API-Key: sa_..."
curl https://api.saaya.ai/api/v1/roles/matrix      -H "X-API-Key: sa_..."

curl -X POST https://api.saaya.ai/api/v1/roles \
  -H "X-API-Key: sa_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "campaign-runner",
    "description": "Can run campaigns but cannot publish agents.",
    "permission_ids": ["…", "…"]
  }'