Permissions
Twenty-one permissions. An account's instance role is a preset over them — authorization is per-permission, never per-role.
Two layers, and only one of them is on this page
A request passes two independent checks:
| Layer | Answers | Where |
|---|---|---|
| Instance permission | May this account reach this route at all? | One guard in front of every route — this page |
| Workspace capability | May it do this to this workspace's data? | Members and roles |
Reaching a route is not the same as being allowed to act. Most project and run work is authorized by the second layer, against the workspace that owns the resource.
The roles
| Role | Permissions |
|---|---|
viewer | run:read, project:read, worker:read, settings:read, workspace:read |
member | …plus run:trigger, run:cancel, run:retry, credential:read |
admin | All twenty-one |
A workspace-scoped service account ignores its role entirely: its effective set
collapses to exactly workspace:read, and the workspace layer confines it to its one
workspace. Scope beats role, so a scoped token can't be escalated by changing the role.
Eight of these are hints, not gates
Thirteen permissions are read by a server-side guard. The other eight have no
server-side reader at all: they are returned in /api/me and drive what the web UI
offers you, while the real check happens in the workspace layer against a capability of
a different name.
They are run:cancel, run:retry, project:read, project:create, project:update,
project:delete, secret:write and worker:read. Each section below says which it is.
Removing project:create from a caller does not stop it creating projects — a workspace
admin can, because createProject is a workspace capability. If you need to restrict
someone, change their workspace role, not their instance role.
Runs
run:read
Read runs, stages and logs. Gate — on the run routes and the live event stream.
run:trigger
Start a run. Gate — on POST /api/runs.
run:cancel
Cancel a running run. Hint. The server authorizes cancellation with the workspace's
cancelRun capability.
run:retry
Re-run a project run. Hint. Authorized with the workspace's retryRun capability.
Projects
project:read
See projects and their configuration. Hint. Project reads resolve the owning workspace and require membership in it.
project:create
Create a project. Hint. Authorized with the workspace's createProject capability,
which is workspace-admin only.
project:update
Change a project's configuration. Hint — updateProject.
project:delete
Delete a project. Hint — deleteProject.
secret:write
Hint, and currently inert. Unlike the other seven hints it has no capability counterpart either; nothing anywhere reads it. Project secrets were replaced by typed credentials.
Credentials
credential:read
List credential metadata. Gate. Values are never returned by any route, at any permission.
credential:write
Create, rotate, re-scope and delete credentials. Gate, and every one of those routes additionally requires a recent re-authentication.
Workers
worker:read
See the worker fleet. Hint — the fleet routes require authentication and nothing more.
worker:drain
Stop a worker claiming new runs. Gate.
worker:remove
Remove a worker record. Gate. The UI offers it only once a worker has gone stale.
worker:identity
Create, relabel, rotate and revoke worker enrolment identities. Gate.
The instance
audit:read
Read the instance-wide audit trail. Gate. A workspace's own activity is readable by its members without this.
settings:read
Read server configuration and announcements. Gate.
settings:admin
Change server configuration, source-control provider apps, announcements, and run the admin operations — garbage collection, reload, backup. Gate.
users:admin
Create, delete and re-role users, and issue their tokens. Gate.
Workspaces
workspace:read
Reach any workspace-scoped route. Gate — and it is the only permission most of those routes carry, because it exists to force authentication and hand off to the workspace layer.
workspace:create
Create a workspace. Gate, and instance admins only. The creator becomes its first workspace admin.