Skip to content
graal — documentation

Roles and permissions

The model holds in three objects: a permission is an elementary right, a role groups several of them, an assignment links a role to a holder on a resource.

Permissions

Section titled “Permissions”

A permission is written <resource>/<action>:

project/create   project/read
bucket/read      bucket/edit
run/create
catalog/read
experiment/create  experiment/read  experiment/edit

They are elementary and non-negotiable: this is what the API checks, call by call. A role that does not contain run/create does not start runs, whatever its name.

Roles

Section titled “Roles”

A role is a named set of permissions. Those of a typical installation:

Role What it allows, in one sentence
Tenant Administrator Administer the tenant: users, groups, roles, assignments, identity providers
Project Owner Everything on their project: jobs, runs, buckets, secrets, project members
Project Reader Read their project without changing anything — the role you grant by default
Bucket Reader Read the files of a bucket, with no right over the rest of the project

The exact catalogue depends on your installation: GET /roles is authoritative, not this table.

Holders: three kinds, one model

Section titled “Holders: three kinds, one model”
Holder What it is When to use it
User A person The common case
Group A set of people, often federated from your directory A data team of 3 to 15: it is the only workable way not to name them one by one
Identity / application A non-human holder: the identity jobs run as, an AI agent’s service account Anything that is not somebody

The point that matters: an AI agent is not a separate category. It carries the rights it was granted, subject to the same checks, and is revoked like a user.

Granting a right

Section titled “Granting a right”
Fenêtre de terminal
curl -s -X POST "$GRAAL_API/assignments" \
  -H "Authorization: Bearer $TOKEN" -H "X-Tenant: $TENANT" \
  -H 'Content-Type: application/vnd.graal.systems.v1.assignment+json' \
  -d '{"role_id":"<role>","principal_id":"<holder>","resource_id":"<resource>"}'

In the console this is the Roles and assignments screen, and revoking is a button on the assignment’s row.

Taking it back

Section titled “Taking it back”

You revoke an assignment, never a role. Deleting a role to take a right away from one person takes it away from everybody; that is the classic mistake.

Fenêtre de terminal
curl -s -X DELETE "$GRAAL_API/assignments/<id>" \
  -H "Authorization: Bearer $TOKEN" -H "X-Tenant: $TENANT"

Giving rights to an agent or a script

Section titled “Giving rights to an agent or a script”
  1. Create an application (POST /applications) — it carries machine credentials.
  2. Assign it the roles it needs, on the relevant projects only.
  3. Use its credentials, never yours.

A script running with a person’s token stops working the day that person leaves, and meanwhile grants itself all of that person’s rights. That is true everywhere; here, there is an object made for it.

What the audit log records

Section titled “What the audit log records”

Every assignment placed or revoked, like every action taken with the rights it grants, is attributed to its actor, human or agent, in the audit log (see security and governance).

Go further

Section titled “Go further”