Scopes

Every API token has a set of scopes that control what it can access. Scopes follow a hierarchy — higher scopes automatically include lower ones.

All Scopes

Scope	Description	Includes
`user:read`	View jobs, workflows, profile, model status	—
`user:write`	Create jobs, execute workflows, submit requests	`user:read`
`admin:read`	View org members, invites, tokens, billing	`user:read`
`admin:write`	Manage org members, invites, tokens, instances, policies	`admin:read`, `user:write`, `user:read`
`worker:read`	GPU worker read access	—
`worker:write`	GPU worker operations (heartbeats, blob upload)	`worker:read`
`system:read`	Infrastructure monitoring (instances, heartbeats, system status)	`admin:read`, `user:read`
`system:write`	Full system administration	`system:read`, `admin:write`, `admin:read`, `user:write`, `user:read`

Hierarchy

system:write
├── system:read
│   └── admin:read
│       └── user:read
├── admin:write
│   ├── admin:read
│   │   └── user:read
│   └── user:write
│       └── user:read
└── user:write
    └── user:read

worker:write          (independent — not included in system:*)
└── worker:read

Worker scopes are independent from the user/admin/system hierarchy. A system:write token cannot access worker endpoints, and a worker:write token cannot access user endpoints.

Presets

Use presets when creating tokens to quickly assign common scope combinations.

User Presets

Available to all users in the dashboard:

Preset	Label	Scopes
`userReadOnly`	User (Read-only)	`user:read`
`userFull`	User (Full)	`user:read`, `user:write`
`adminReadOnly`	Admin (Read-only)	`admin:read`
`adminFull`	Admin (Full)	`admin:write`

System Presets

Available to system org admins only (Admin UI):

Preset	Label	Scopes
`worker`	Worker Service Account	`worker:write`
`systemReadOnly`	System (Read-only)	`system:read`
`systemFull`	System (Full)	`system:write`

Role-Based Scope Limits

A user’s org role limits the maximum scopes they can assign to tokens:

Role	Maximum Scopes	Can Create Service Accounts
Owner	`admin:write` (+ `system:*` if system org)	Yes
Admin	`admin:write` (+ `system:*` if system org)	Yes
Member	`user:write`	No
Disabled	None	No

When a token is used, its effective scopes are the intersection of the token’s scopes and the user’s role scopes. If a user is downgraded from Admin to Member, their existing admin-scoped tokens lose access to admin endpoints.

Recommendations

Use Case	Recommended Scopes
CI/CD pipeline (submit jobs, read results)	`user:read`, `user:write`
Read-only dashboard / monitoring	`user:read`
Org management automation	`admin:write`
Monitoring-only admin access	`admin:read`
GPU worker service account	`worker:write`

For CI/CD and automation, prefer the User (Full) preset — it grants access to all data plane operations without org management privileges.

Token Types

Type	Created By	Visible To	Use Case
Regular API token	Any user	Token owner (members), all tokens (admins)	API access, integrations
Service account	Admins only	Admins only	Automation, CI/CD with elevated privileges
Session token	OAuth login (automatic)	Hidden in dashboard	Browser sessions

See the API Tokens guide for how to create and manage tokens.