Roles & Permissions

Corveil authorizes on capabilities — fine-grained permissions like "manage billing" or "read your own logs" — and bundles them into a small set of predefined roles. A check always asks "does this person hold this capability?", never "is this person an admin?", so the dashboard, the HTTP API, the MCP control surface, and the CLI all enforce the same rules.

Roles are scoped to one organization. There is no system-wide administrator and no impersonation path — a person's role is resolved per request against the organization they are acting in, and a role in one org grants nothing in another.

The organization roles

Every user in an organization holds exactly one organization role. On each team they're on, they also hold a team role; see Team roles.

Role	What it's for
Owner	The break-glass principal. Full administrative access plus protection an identity-provider sync can never override — an org always keeps at least one owner.
Admin	Full administrative access: reconfigure the org, manage users, billing, models, guardrails, credentials, automation, and more.
Billing admin	A finance contact who manages the subscription, payment method, and plan — and nothing else.
Budget viewer (all teams)	Views the AI-spend budget of every team in the org, for someone like a CFO. They cannot change budgets, mint keys, call the gateway, manage users, or manage the Corveil subscription.
Budget stakeholder (retired)	Views the budgets of teams they belong to. No longer offered: use Viewer plus the Budget viewer team role instead. People who already hold it keep their access.
Member	The general-purpose seat: mint your own API keys, call the gateway, author the knowledge graph, and read your own traffic.
Gateway user	A programmatic API consumer: mint your own keys and call the gateway, without authoring the graph or reconfiguring the org.
Viewer	Read-only. See your own logs, sessions, usage, and Insights — no key minting, no gateway calls, no writes.

Owner and admin hold the same capabilities. The difference is two guarantees, not access: an owner is marked protected (an SSO/SCIM directory sync cannot demote or remove it) and an org can never drop its last owner.

Capabilities grow monotonically along the main line viewer → gateway user → member → admin (= owner) — each holds everything the one before it does, plus more. Billing admin and budget viewer (all teams) sit off to the side. Billing admin can manage billing (which member cannot) but holds none of member's write access. Budget viewer (all teams) matches viewer's organization access, and can additionally view every team's budget. To let someone view only some teams' budgets, give them the Budget viewer team role on those teams instead — they keep their organization role.

What each role can do

Reads that are part of an org's shared context — the list of users, teams, the enabled-model list, the knowledge graph, published dashboards, the billing plan — are available to any user in the org, whatever their role. Everything below is the restricted surface each capability unlocks.

Capability area	owner	admin	billing admin	budget viewer (all teams)	member	gateway user	viewer
Organization settings, teams, users, invitations	✅	✅	—	—	—	—	—
Billing (checkout, portal, plan changes)	✅	✅	✅	—	—	—	—
Models, guardrails, credentials, sensors, automation, MCP admin	✅	✅	—	—	—	—	—
Author the knowledge graph (create/update entities & links)	✅	✅	—	—	✅	—	—
Destructive graph ops (delete/merge/split), type registry	✅	✅	—	—	—	—	—
Author dashboards	✅	✅	—	—	—	—	—
Analytics, org-wide usage & spend, full-org log export	✅	✅	—	—	—	—	—
View every team's AI-spend budget	✅	✅	—	✅	—	—	—
Change team AI-spend budgets	✅	✅	—	—	—	—	—
Mint & manage your own API keys	✅	✅	—	—	✅	✅	—
Call the read-only gateway-invoke path	✅	✅	—	—	✅	✅	—
Read your own logs, sessions, usage, Insights	✅	✅	✅	✅	✅	✅	✅

Owners and admins view and change every team's budget. A budget viewer (all teams) views every team's budget and changes none. The budget rows above show what each organization role grants by itself. A team role adds to it for that one team, whatever the organization role: a Budget viewer views that team's budget, and a Team admin views and changes it. So a dash in any column does not apply to a team where the user holds one of those team roles — see Team roles. The retired budget stakeholder role has the same column as viewer, plus viewing the budgets of teams its holder is on.

Team roles

A team role is separate from the organization role. A user can be on any number of teams, and on each team they hold one team role:

Team role	Adds, for that team only
User	Nothing beyond being on the team.
Budget viewer	Viewing the team's AI-spend budget and spend limits.
Team admin	Viewing and changing the team's budget and spend limits, and reading the team's request logs.

• The team role never replaces the organization role. A Gateway user who is Budget viewer on Sales still mints keys and calls the gateway; a Viewer who is Team admin of Sales still can't mint a key.
• It grants nothing on any other team. Budget viewer on Sales doesn't show Engineering's budget.
• The higher role wins. The roles rank User < Budget viewer < Team admin. When a person gets two roles on one team — for example from two directory groups — they hold the higher one.
• Budget approvals are not a separate role yet. A Team admin changes the team's budget directly.

An admin sets a user's team role on People & Access → Teams. The organization role is set on People & Access → Users. With SSO directory sync, a directory group can assign a team role instead — see Team roles from your directory.

A Team admin changes their team's spend limits under Governance → AI Gateway, on the Spend limits tab (page title Team spend limits). An org admin uses the Guardrails tab on that same page (page title Guardrails). A Budget viewer, and a Budget viewer (all teams), sees them there read-only. People without the guardrails capability see only team spend limits on that page, not the org's other guardrails.

Which team spend counts against

Each request counts against one team's budget, and a team's spend limit caps exactly the spend its usage card shows:

• A key bound to a team counts against that team, whoever uses it.
• Everything else (chat and session usage, or a key with no team) counts against the person's primary team: their oldest team other than default where they're a User or Team admin. A Budget viewer row never makes a team primary. default is used only when the person has no other team.
• With SSO directory sync, a person's Default API key is bound to their directory team when they're on exactly one, so a person in one mapped group spends against that group's team. See Directory mappings.

The primary team is worked out when the total is read, so adding someone to their first team other than default, or removing them from it, moves their past unattributed usage with them.

An owner or admin can also act on a teammate's API keys and per-user usage — the owner of a resource or an org admin may use those endpoints, and an admin creating a key on a teammate's behalf simply names the target user. One thing stays owner-only by design: editing another user's profile — a teammate's display name and personal budget are theirs to set, so an admin makes org-level changes through the membership surfaces (role, removal) instead.

The org boundary — Diagram E

What each role can do, and the fact that a role in one organization grants nothing in another. Virtual API keys sit inside that same boundary — every key is scoped to one org (and a team and a user), and the real provider credentials never leave the gateway.

Reading it:

• The box is the boundary. Everything every role can do lives inside one organization. Nothing crosses the dashed line — a user who is an admin of Org A holds only the role Org B gave them in Org B, until an existing Org-B admin changes it.
• Management vs. use vs. read. Owners and admins hold the management surfaces; users with the Member or Gateway user role hold the "use the gateway" surfaces; viewers read their own activity. Billing admin manages billing and nothing else. A budget viewer (all teams) views every team's budget and cannot change them. Team roles (not shown) add budget access on single teams.
• API keys are scoped, and provider keys are shielded. A virtual key is bound to the org, a team, and a user — that scoping is what makes spend and logs attributable. The real provider credentials stay in the vault; a key holder authenticates to the gateway and never sees them.

Transfer admin

To hand an organization to someone else, an admin uses Transfer Admin: it promotes the chosen user and demotes the current admin in a single step, so the org never passes through a state below its break-glass floor.

Invariants

These behaviors are guaranteed and separately tested.

Every org keeps a break-glass principal (the last-owner invariant)

An organization always retains at least one principal who can administer it.

You cannot demote, remove, or "leave organization" your way to an org with no owner (or, for an org that predates the owner role, no admin). When an operation would cross that floor it is rejected with 409 Conflict. The dashboard also hides the affordances that would trip it, so the error is a backstop, not something you normally hit. An owner additionally cannot be demoted or removed while it is the last owner — even by an admin — and an identity-provider sync can never demote a protected owner.

Roles are per-org

A person's role in org A says nothing about their role in org B.

Promotion and demotion write a single membership, in a single organization. There is no "admin everywhere" path. An admin of org A who is invited to org B joins in whatever role the invitation specifies and stays there until an existing org-B admin changes it.

Roles do not encode plan tier

The set of roles is identical across every plan.

Plan tier gates which features an org can use — not which roles its users can hold. A trial admin and an enterprise admin have identical role-derived access; the differences are usage caps and enterprise-only features (SSO, SCIM, and domain verification), never the role model itself.

Roles come from Corveil, and SSO maps onto them

Corveil is the source of truth for roles.

For organizations using SSO with directory sync, an admin maps an identity-provider group, or a value of the corveilRole directory attribute, onto a Corveil role on People & Access → Directory Mappings (Group & attribute → Role). The first matching rule wins, and the mapping is re-applied on every sync. But the role always resolves to a Corveil capability bundle — there is no dependency on the identity provider's own role system, and a directory sync can never lock an org's owner out of its own tenant.

• Directory Sync assigns the role, not the sign-in. Role mapping runs when Directory Sync (SCIM) provisions or updates a person. Signing in with SSO doesn't change a role, even when the SAML assertion carries a corveilRole attribute.
• The attribute name is fixed. Corveil defines corveilRole for every organization; you don't invent or type the name. Map one of your directory fields onto it once, under Configure SCIM on People & Access → Organization.
• Each value maps to a role. In Corveil, add a rule per value, such as viewer → Viewer. A person with no matching value keeps their current role.
• Team roles come from groups. A directory group can also make its members Budget viewer or Team admin on one directory team (Group → Team role). The retired budget stakeholder role can't be picked for a new rule; an existing rule that targets it keeps working and is flagged, so you can point it at Viewer and add Budget viewer role groups.

See SSO, SCIM & Domain Verification for the setup.

What isn't here

• Custom roles. Today Corveil ships a fixed set of predefined roles. A custom-role builder that composes arbitrary capability sets is planned but not yet available.
• Per-resource sharing. Access is by role, org-wide (with the narrow team roles above as the exception). "This person can edit records A and B but not C" — a per-resource ACL — is out of scope. Per-resource ownership already governs a few surfaces (your own API keys, your own profile), but that is ownership, not a role.