# Roles

Four roles, and the set is closed. The same four words describe what a person may do and what a key may do, so there is one vocabulary to learn and one answer to give when a review asks who can spend money and who can only look.

| Role | May |
|---|---|
| `admin` | Everything below, plus issue and revoke keys, write policies and budgets, manage members and billing, and register model endpoints and storage backends. |
| `agent` | Resolve and execute actions, submit jobs, and connect accounts for the entities it acts for. This is the role an assistant holds. |
| `approver` | Release parked approvals and answer asks addressed to approvers. Changes no configuration. |
| `viewer` | Read everything the governance surfaces show. Changes nothing. |

## The rules that follow

**One role per key.** A key has exactly one role. A person who needs two capabilities holds two keys, which is what makes revoking one of them a precise act.

**Separation of duty binds, and `admin` does not escape it.** An approver key never releases work its own key id submitted. An administrator who submitted a job cannot approve it with the same key either. The check is on the key id rather than on the role, so widening a role never widens this.

**Member management is session-only.** Adding, removing, or re-roling a person needs a signed-in person. An API key has no user behind it, so no key can do it whatever its role. That refusal is the design and not a gap.

**Viewer seats are free.** Read-only access costs nothing on every tier, because an organization that has to pay per person to let its risk team look will not let its risk team look.

## Organization and project

A person holds a role in the organization and can hold a different role on a project. The narrower of the two decides what they can actually do there.

That is the shape most organizations want: `viewer` at the organization so somebody can see the whole picture, `admin` on the one project they own. It also means a project can be genuinely isolated from a colleague who is an organization member.

The owner is one person, distinct from the role. The owner holds `admin` and cannot have that role changed out from under them; moving it is a transfer that the receiving administrator has to accept.

## Choosing roles in practice

Start from what breaks if the credential leaks.

An assistant needs `agent` and nothing more. It cannot change a policy, so a compromised assistant key cannot widen its own limits, and that property is the reason to resist granting it more.

The person who answers approvals needs `approver`. Giving them `admin` so they can also adjust a budget defeats the separation, because the same key would then both raise a ceiling and approve the call that crosses it.

A dashboard, a monitor, or an auditor needs `viewer`. It is free, and it means the read-only integration cannot become a write path later by accident.

Reserve `admin` for the small number of people who genuinely administer the deployment, and give those keys an expiry when you mint them.

## Changing a role

Role changes are administrative acts and every one of them is recorded: who changed it, whose role moved, when, and from what to what. [The audit record](./the-audit-record.md) is where that lands, and it is the answer to the question a review always asks, which is not what the roles are but when they last changed.