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 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.