Roles & Permissions
This page is the reference: what every org role and workspace role can do, how custom role templates are composed, and how scoped usage/cost reporting works.
Org roles
Set once per user account (User.role), scoped to their organization.
| Role | Scope | Capability |
|---|---|---|
superadmin | Platform-wide, not org-scoped | Manages organizations, SSO config, the model catalog, and the global role-template library. Bypasses every require_role/require_action check, including the documents.acl.bypass / audit.read / audit.export carve-outs — a superadmin always passes those too. |
admin | One organization | Auto-holds every permission in the catalog except documents.acl.bypass, audit.read, and audit.export (must come from an explicit role-template grant — see RBAC overview). Manages that org's workspaces, users, and role assignments. |
user | One organization | No implicit capability beyond the built-in read-only default (workspace.read, documents.list, documents.content.read, search.execute, chat.read, chat.generate, reports.view.self). Real capability comes from an assigned custom role template. |
Workspace roles
Set per member, per workspace (WorkspaceMember.role), independent of the
org role above — a user-tier account can be a workspace owner.
| Role | Capability |
|---|---|
owner | Department admin. Manages this workspace's own membership (add/remove members, change their workspace role) and sees the department's usage/cost reports. |
manager | Department admin, same as owner in practice today — manages membership and sees department reports. |
contributor | Regular member. Whatever their org-level permissions (default floor or role template) allow — typically upload, chat, search — scoped to this workspace's membership. |
viewer | Regular member with the lowest expected footprint — read/search/chat, no content mutation, per whatever their permissions actually grant. |
The workspace role itself doesn't carry permission bits directly (that's what
role templates and the org tier are for); owner/manager are the signal
the Members tab in workspace settings uses to mark someone as this
department's admin — see
Organizations & Workspaces.
Custom role templates
A role template is a superadmin-authored, named bundle: name,
description, and a flat permissions: list[str] of dotted action flags
drawn from the full catalog below. An org admin assigns a template to a
user-tier account (custom_role_id); that account's effective permission
set becomes exactly the template's list — no default floor added on top,
no inheritance from anywhere else.
Lifecycle. Templates carry a draft → active → archived status and a
monotonic version. A new template starts as draft; activate flips it
to active, bumps the version, and writes an immutable version snapshot.
Rollback restores the previous snapshot's permissions and activates that
as a new forward version — history is never rewritten, only added to,
mirroring the audit log's append-only discipline. Before editing or deleting
a template, the impact endpoint reports how many users are currently
assigned it, so a superadmin can see the blast radius first. A template that
still has at least one assigned user cannot be deleted (409).
A dangling role reference fails closed
If a user's custom_role_id points at a template that no longer exists —
a corrupted row or an out-of-band write, since the foreign key is
ON DELETE SET NULL in the normal flow — that account gets zero
permissions until an admin re-assigns a real template. It never silently
falls back to a broad default; a broken reference must never mean more
access.
Seeded templates
Ragz ships eight ready-to-use templates covering the common patterns, so most orgs never need to hand-author one:
| Template | Covers |
|---|---|
| Contributor | The pre-deny-by-default baseline: upload, delete, move, pin documents; chat (including attachments and delete); search. The default assignment for any existing user account when the platform narrowed its default floor. |
| Viewer | Read-only: browse, search, and chat — no mutation. |
| Content Manager | Library management: upload/delete/move/pin, ACL and approval authority, including the explicit documents.acl.bypass grant. |
| Workspace Owner | Full workspace governance: settings, re-embed, and membership. |
| Workspace Manager | Workspace settings and membership, without re-embed authority. |
| IAM Admin | User/group administration — no automatic ACL bypass, no audit access. |
| Audit Reader | audit.read + audit.export only — can review and export evidence, cannot administer access (NIST AC-5 separation of duties). |
| Service Principal | The documented floor for a user account backing an API key or bot integration: search.execute, chat.read, chat.generate. |
The full permission catalog
Every action a route can declare, grouped by area. Role templates compose from this exact list (an unknown action is rejected when a template is created or edited).
| Group | Permissions |
|---|---|
| Workspace | workspace.read, workspace.create, workspace.configure, workspace.reembed, workspace.members.read, workspace.members.manage, workspace.metadata.manage |
| Documents | documents.list, documents.content.read, documents.upload, documents.metadata.update, documents.move, documents.pin, documents.delete, documents.acl.manage, documents.acl.bypass, documents.approve |
| Folders | folders.read, folders.create, folders.update, folders.delete |
| Knowledge / chat | search.execute, chat.read, chat.generate, chat.update, chat.attachments.create, chat.delete, chat.feedback |
| Users / groups | users.read, users.invite, users.activate, users.role.assign, groups.read, groups.manage |
| Policy / audit | roles.read, roles.author, roles.assign, audit.read, audit.export |
| Operations | models.read, models.manage, secrets.manage, sso.manage, integrations.manage, api_keys.manage, quota.read, quota.manage, analytics.view, feedback.review, evals.read, evals.manage, evals.run, platform.health, platform.orgs.manage, settings.manage, client_errors.report |
| Cost reporting | reports.view.self, reports.view.department, reports.view.org, reports.view.platform |
documents.acl.bypass, audit.read, and audit.export are the three
carve-outs from the RBAC overview — they never come from the
admin/superadmin auto-grant, only from an explicit template.
Reporting scopes
Usage and cost reports (Reports) escalate through four scopes, each
gated on its own permission — except platform, which is deliberately gated
on the concrete superadmin role, not a permission flag, because an org
admin auto-holds every non-carve-out permission and trusting a
reports.view.platform action alone would leak every org's cost data to any
org admin:
| Scope | Sees | Gate |
|---|---|---|
self | The caller's own usage/cost. The reporting floor — every member holds it by default. | reports.view.self |
department | A workspace's aggregate usage/cost. | reports.view.department (auto-held by admins) |
org | The whole organization's usage/cost. | reports.view.org (auto-held by admins) |
platform | Every organization's usage/cost. | ctx.role == "superadmin" only — never satisfied by holding the action alone |
This is also why owner/manager workspace roles are described as
"department admins that see department reports" — in practice that means the
admin who assigned them a role template with reports.view.department.