Roles and permissions#

This page is the reference for authorisation in Astraeus: organisation roles, workspace roles, and what each allows. For how to give people roles, see Members, roles and SSO.

Two layers#

Layer	Who	Roles	Applies to
Organisation	People in an organisation	`owner`, `admin`, `member`	The organisation: members, workspaces, clusters and machines, SSO, alerts, prices
Workspace	People in a workspace	`admin`, `editor`, `viewer`, `auditor`	What is inside the workspace on each cluster

When you act in a workspace — from the console, astra or the API — Astraeus authorises the request as your workspace role, inside that workspace only: paths must name objects in it, bodies may name and reference only objects in it, and listings and watches show only it.

Organisation owners and admins act with the workspace role admin in every workspace of the organisation.

Organisation roles#

Capability	owner	admin	member
Read the organisation, its members, its clusters and their prices	✓	✓	✓
Usage of the workspaces they belong to	✓	✓	✓
Usage of every workspace, and of work outside workspaces	✓	✓
Rename the organisation	✓	✓
Invite (`admin`, `member`), list and revoke invitations	✓	✓
Change roles between `admin` and `member`; remove non-owners	✓	✓
Grant or revoke `owner`; remove owners	✓
Create and delete workspaces; give them access to clusters and set their terms	✓	✓
Use Astraeus Cloud; enrollment tokens (add machines); cordon, label, upgrade and remove machines; data locations; reservations; clear GPU faults	✓	✓
Set cluster prices	✓	✓
Single sign-on, audit log, alerts, event streams, organisation guardrails and marketplace settings	✓	✓
Delete the organisation (only without clusters)	✓

Refusals: 403 ORG_ADMIN_REQUIRED, 403 ORG_OWNER_REQUIRED; outsiders get 404 ORG_NOT_FOUND.

Workspace roles in the console#

Besides the permissions inside a workspace on a cluster (below), these workspace actions are checked by the console:

Action	viewer	editor	admin	auditor
See the workspace, its people, its clusters and their terms	✓	✓	✓	✓
See the workspace's events and run list	✓	✓	✓	✓
Use run templates	✓	✓	✓	✓
Save and delete run templates		✓	✓
Add, change and remove people; rename the workspace; event retention; hosted inference gateway			✓
Remove themselves from the workspace	✓	✓	✓	✓

Refusals: 403 WORKSPACE_ADMIN_REQUIRED, 403 WORKSPACE_EDITOR_REQUIRED; someone outside the workspace gets 404 WORKSPACE_NOT_FOUND.

How a request maps to a verb and a resource#

Astraeus names every request with a verb and a resource, as Kubernetes does. Paths are relative to a workspace's cluster path (…/clusters/{cluster}/api; see REST API).

Request	Verb
`GET` (or `HEAD`) on a collection, `/jobs`	`list`
`GET` on a collection with `?watch=true` (or `watch=1`)	`watch`
`GET` on an object, `/jobs/train`	`get`
`POST`	`create`
`PUT`, `PATCH`	`update`
`DELETE`	`delete`
Anything under `/<collection>/<name>/proxy/…`	`proxy`

Path	Resource
`/<collection>` and `/<collection>/<name>`	`<collection>`
`/<collection>/<name>/<sub>…`	`<collection>/<sub>`, for example `tasks/logs`, `cronjobs/trigger`
`/metrics/<kind>…`	`metrics/<kind>`

The resources' product names are aliases of their API names, and authorization always sees the API name: runs is jobs, workers is tasks, machines is nodes, drives is datavolumes, mounts is datavolume-claims, data-sources is connectors, credentials is external-secrets, schedules is cronjobs, replica-groups is scaling-groups, reservations is node-reservations.

A rule names verbs and resources:

A resource jobs covers the collection and its objects, not its subresources. jobs/* covers every subresource. * covers everything.
The verbs are get, list, watch, create, update, delete, proxy and *. Read verbs never include proxy.

Permissions inside a workspace#

A request in a workspace passes two checks: first, whether the path is available inside a namespace at all; then, whether the role allows the verb on the resource. A refusal names which: 403 NAMESPACE_FORBIDDEN or 403 RBAC_FORBIDDEN (for example role viewer may not create jobs in ws-3f9a1c07b2e4).

Astraeus resources#

✓ allowed · — refused. "Read" is get, list and watch.

Resource	Product	viewer	editor	admin	auditor
`jobs`	Runs	read	✓	✓	—
`jobs/external-accesses`	A run's external access	`get`	✓	✓	—
`tasks`	Workers	read	✓	✓	—
`tasks/logs`, `tasks/trace`, `tasks/activity`	A worker's log, tool-call trace, outbound activity	`get`	✓	✓	—
`tasks/stop`, `tasks/requeue`	Stop or requeue a worker	—	✓	✓	—
`tasks/proxy`	Reach a worker's port through Astraeus	—	✓	✓	—
`cronjobs`, `cronjobs/pause`, `cronjobs/resume`, `cronjobs/trigger`	Schedules	read (not the actions)	✓	✓	—
`scaling-groups`, `…/pause`, `…/resume`, `…/activate`	Replica groups	read (not the actions)	✓	✓	—
`endpoints`	Endpoints	read	✓	✓	—
`endpoints/proxy`	Reach an endpoint through Astraeus	—	✓	✓	—
`datavolumes`	Drives	read	✓	✓	—
`datavolume-claims`	Mounts	read	read	read	—
`connectors`	Data sources	read	✓	✓	—
`connectors/index`, `/files`, `/partitions`, `/profile`, `/diff`	A data source's catalog	`get`	✓	✓	—
`connectors/reindex`, `connectors/scan`	Re-index or scan a data source	—	✓	✓	—
`external-secrets`	Credentials (references only; values never reach Astralyx)	read	✓	✓	—
`external-secrets/resync`	Fetch a credential again	—	✓	✓	—
`nodes`, `nodes/tasks`	Machines in the workspace's pools, and what holds their GPUs	read	read	read	—
`gpus`	The GPUs of those machines	`list`	`list`	`list`	—
`metrics/…`	Machine series, and the workspace's run and worker series	read	read	read	—
`usage`	The workspace's hourly usage	`list`	`list`	`list`	`list`
`namespaces` (its own)	The workspace's namespace and terms	`get`	`get`	`get`	`get`
`interactive` (`interactive/<worker>/proxy`)	An interactive run's server	—	✓	✓	—

Always refused inside a workspace, whatever the role: writes to machines, mounts and namespaces; reservations; enrollment tokens; another workspace's objects. Organisation admins manage machines, reservations and enrollment through the console's organisation pages and cluster endpoints. On machines, other workspaces' work is shown only as taken capacity — its GPUs and size, never its name or owner.

Other products#

The same roles cover Eos, Anemoi and Hesperus resources in the workspace. In short: viewers read; editors write, except that agent guardrails, agent budgets and retention policies are written by admins only (editors read them); auditors read the agents' governance record (agents and their versions, runs, costs, receipts, traffic and quality; approvals, guardrails, budgets and costs; flows and executions; eval runs; retention policies; usage) and create, download and delete evidence packs, which only admins and auditors may touch.

Machines#

Machines are not people and have no role. A machine's credential lets it act only for itself: receive the work placed on it, report on itself and its own workers, and answer requests addressed to it. It cannot read or change anything in a workspace. See Security model.