Permissions and tokens
Roles and scopes
Section titled “Roles and scopes”Every request is allowed only if both of these allow it:
- the role of whoever the credential acts for: a person’s project role (organization owners and admins are admins of every project), or a service token’s own role;
- the credential’s scopes, and its project list when it has one.
A scope never widens a role. A token with runbooks:publish held by an
operator still can’t publish.
| Scope | Lets the credential | Role needed |
|---|---|---|
runbooks:read |
Read runbooks, versions and drafts | viewer |
executions:read |
Read runs, steps, reports and archives | viewer |
skills:read |
Read skills | viewer |
executions:start |
Start runs | operator |
executions:act |
Work on runs: claim and report steps, decide approvals it’s eligible for, mint execution pairs | operator |
executions:admin |
Override a step’s result and edit a run (runbook run update) |
operator |
runbooks:write |
Create runbooks and save drafts | editor |
skills:write |
Upload skills | editor |
runbooks:publish |
Publish versions, sync from Git | editor |
tokens:manage |
Create, list and revoke tokens | admin |
webhooks:manage |
Manage webhook subscriptions | admin |
project:admin |
Members, project settings and variables | admin |
An archived project is read-only for everyone: only the :read scopes work
there.
Kinds of credentials
Section titled “Kinds of credentials”| Credential | Prefix | Acts as | Lifetime |
|---|---|---|---|
| Personal access token | trb_pat_ |
A person | 90 days by default, at most 1 year |
| Agent-kind token | trb_pat_ |
An agent, sponsored by the person who made it | Like a personal token |
| Service token | trb_svc_ |
A project’s automation, with its own role | Until revoked, or an expiry you set |
| Execution pair | trb_exe_ / trb_exr_ |
An agent working one run | Access 1 hour; refresh family at most 30 days, only while the run is open |
| OAuth access token | trb_oat_ |
An agent sponsored by the person who consented (MCP clients) | 1 hour; refresh within 90 days of consent |
| Browser session | cookie | A person | Until sign-out or expiry |
Tokens are issued only to the caller: POST /v1/tokens never creates a
token for someone else, and a token can carry only scopes its creator holds,
never past the creator’s own token’s expiry. Only organization owners and
admins issue service tokens.
# a person's narrow, short-lived tokenrunbook token create --name laptop --scope runbooks:read --scope executions:read --expires-in 7d
# an agent you sponsorrunbook token create --agent --name ci-agent --scope executions:read --scope executions:act --project prod
# a project's launcher, which only mints execution pairsrunbook token create --kind service --role operator --project prod \ --scope executions:read --scope executions:act --name launcher
runbook token listrunbook token revoke tok_…Least access, by caller
Section titled “Least access, by caller”| Caller | Give it |
|---|---|
| A person at the CLI | runbook login: the default scopes, through the browser |
| A person’s browser | A session from sign-in |
| An agent working one run | An execution pair, minted by a launcher |
| An agent on a developer’s machine | An agent-kind token with runbooks:read, executions:read and executions:act, limited to its projects, expiring |
| A webhook launcher | A service token with executions:read and executions:act |
| CI that publishes runbooks | A service token, role editor, with runbooks:read and runbooks:publish |
| A webhook trigger sender | A token with executions:start in that project |
Execution pairs
Section titled “Execution pairs”A launcher with executions:act mints a pair for one run:
RUNBOOK_TOKEN="$SERVICE_TOKEN" runbook run token exe_… --session agent-1- The access token reaches only that run, and only the step its session has claimed.
- The CLI refreshes it from the refresh token. Reusing a refresh token that was already used revokes the whole family (a stolen copy can’t keep working).
- Every pair is revoked when the run ends.
Connected apps
Section titled “Connected apps”MCP clients that signed in with OAuth are listed per person, and can be disconnected at once:
runbook apps listrunbook apps revoke <client_id>On the consent page, runbooks:publish is unticked by default, and a grant
is narrowed to the person’s role.