Roles and Permissions

Human administration and API inference are independent. Roles authorize management operations on an Organization or Team. Virtual-key policy authorizes model/tool/deployment calls and telemetry ingestion. An Agent is content, not a principal or role-assignment target.

Eight built-in presets

Preset	Scope	Intended authority
organization.owner	Organization	All management permissions, including protected ownership recovery
organization.admin	Organization	All management permissions except ownership management
organization.auditor	Organization	Organization/people/role/Team/catalog/app/deployment metadata, usage, budgets, Observe metadata/export and audit; no captured content; evaluation metadata
organization.billing	Organization	Organization/Team metadata, usage, budgets read/manage and allocation
organization.member	Organization	Organization metadata; no automatic Team or inference access
team.admin	Team	All Team management permissions except captured-content and evaluation-content read
team.developer	Team	Team/catalog/app/deployment metadata, own-user key creation/management, Agent edit/test, usage/budgets read and Observe metadata, evaluation management, review and experiment execution
team.viewer	Team	Team/catalog/app/deployment metadata, usage/budgets read, Observe metadata and evaluation metadata

Preset permissions are reconciled at gateway startup, so an upgrade that adds a permission reaches existing Organizations without administrator action. Presets are immutable. Clone/create a custom role with a bounded subset of the registry, at Organization or Team scope. Organization roles can cover Team permissions across the Organization; Team roles cannot contain Organization-only permissions. organization.ownership.manage is protected from ordinary custom-role and directory assignment. Owner recovery is explicit and audited; the last owner's authority cannot be removed through ordinary management.

Grants stay within your own authority

A person cannot hand out authority they do not hold. The rule applies to every way a role reaches someone: an Organization or Team role assignment, a Team membership source, a directory group mapping and a management token acting for its owner.

• Assigning a role. You need the scope's assignment permission (people.manage for Organization roles, team.members.manage for Team roles) and every permission the role contains at that scope. An Organization role's permissions must be yours Organization-wide; a Team role's permissions may come from your Organization roles or your roles in that Team.
• Team presets. Whoever may manage a Team's members may also give its team.admin, team.developer and team.viewer presets to other people in that Team when the only permissions a preset carries beyond their own are the content-read permissions evaluation.content.read and observability.content.read. This keeps a team.admin able to add developers: team.developer includes evaluation.content.read, which team.admin does not. Any other permission a preset carries must be yours, so a person who can only manage members cannot give team.admin. The exception never reaches the granter: in Team membership, choosing yourself with such a preset is refused with You can't give yourself this role: it carries permissions you don't hold in this Team. It never applies to a directory group mapping either, because the identity provider can add you to the group later; a mapping needs every permission the role contains.
• Defining a role. Creating or changing a custom role needs roles.manage and, Organization-wide, every permission the new definition contains. Team roles can be assigned in any Team, so Team permissions held only in one Team do not count.
• Management tokens. A token grants only permissions it carries itself, so a token without a role's permissions cannot assign that role.

A refused grant changes nothing. The Console offers only the roles you may grant at the scope to other people; the management API answers 403 with not_authorized. Ask someone who holds the missing permissions — an Organization administrator holds all of them except ownership — to make the grant.

A Reviewer for domain experts is a custom Team role of team.viewer plus evaluation.review and evaluation.content.read. A Reviewer who grades Trace subjects in a review queue also needs observability.content.read on that Team to see the captured request and response, which no preset below organization.admin grants; a Reviewer of experiment items does not.

Management permission registry

Scope	Permissions	Purpose
Organization only	organization.read, organization.settings.manage, organization.ownership.manage	Organization metadata, startup configuration/diagnostics and protected ownership
Organization only	people.read, people.manage, roles.read, roles.manage, teams.create	People lifecycle, role definitions/assignments and Team creation
Organization only	budgets.allocate	Allocate governance ceilings
Organization or Team	team.read, team.manage, team.members.manage, team.allowance.manage	Team metadata/status, sources/membership, resource allowance and telemetry deletion
Organization or Team	catalog.read, service_accounts.manage	Catalog metadata and ordinary service-account lifecycle
Organization or Team	keys.user.create, keys.user.manage, keys.manage, keys.service.manage	Own-user creation/management, other-user key management, service keys
Organization or Team	agent.read, agent.edit, agent.test	Application content and private Preview
Organization or Team	deployment.read, deployment.publish, deployment.manage, deployment.access.manage, deployment.execute	Deployment metadata, version publication, lifecycle, access/policy/caps and managed test execution
Organization or Team	usage.read, budgets.read, budgets.manage	Financial summaries, constraint details and operating caps
Organization or Team	observability.read, observability.content.read, observability.export	Team metadata, sensitive captured content and export, independently
Organization or Team	audit.read, namespaces.manage, approvals.decide	Audit, ordinary namespaces/grants and administrator tool approval
Organization or Team	evaluation.read, evaluation.content.read, evaluation.manage, evaluation.review, evaluation.execute	Score definitions, scores and datasets as metadata; item bodies and score comments; definition and dataset management; recording and retracting own scores; starting, cancelling and archiving experiments, which consume Team funding

A key manager may narrow their manageable ordinary key's operating cap without gaining ancestor budget detail. Production execution caps require deployment.access.manage or budgets.manage; a private Preview creator may manage its local cap with current Team membership and agent.test. These bounded paths do not grant general budget administration.

What pickers reveal

Console forms list the things they need by name. A person who may perform an action sees the names that action needs, and nothing more: a picker entry carries an ID, a name and one line of context, and grants no access to the listed item.

Permission	A picker reveals
team.allowance.manage	Names of the Organization's models, tools and tool sets, and of the Team's active production deployments
keys.user.create, keys.user.manage, keys.service.manage, keys.manage	Names of the models, tools, tool sets and deployments the Team allowance permits
evaluation.manage	Names of the Team's ordinary keys that are not revoked, each with its owner's name — a person or a service account (the auto-evaluation Key picker)
evaluation.read, evaluation.content.read, evaluation.manage	Names of the tools the Team allowance permits and their connector names, without catalog.read, and the names and versions of the Team's active score definitions, evaluators, datasets, dataset slices and experiment templates, already readable on the Evaluate pages (the bundle import pickers)
evaluation.manage	Names, connectors, classifications and schema hashes of the registered read-only tools the Team allowance permits, and for each argument its name, whether it is required and its declared primitive type (the tool-validator Tool picker); never the rest of a tool's input schema
evaluation.read, evaluation.content.read, evaluation.manage	Titles and external IDs of a dataset's active cases, its tags with case counts, and its metadata key names with the value types seen, never a metadata value (the slice Filter controls). The same permissions already show all of this on the dataset page
team.members.manage	Names and email addresses of active Organization members, only in answer to a search of at least two characters and at most 50 people per search (the Team Person picker). Nobody is listed before a search, and people.read is not needed
observability.read	Names and owners of the keys that appear in the requests of the readable Teams inside the reporting window (the Key filter of Requests, Traces and Sessions), and of a key of a readable Team that the address already names
usage.read	Names and owners of the keys that appear in the upstream attempts of the readable payer Teams inside the reporting window (the Key filter of Usage), and of a key of a readable Team that the address already names
evaluation.read	Names of the Team's Agents that appear in its scores inside the reporting window, archived Agents included (the Agent filter of Scores); agent.read is not needed
audit.read	The action names recorded in the readable audit scope (the Action filter of Audit), which the Action column already shows

What pages name

Console pages show the names of what a record refers to, read under the permission the page already showed that record with. A name only: never an email address, a status, a role or anything else.

Permission	A page names
observability.read	On the Requests table and on the request, Trace, Session and capture pages of a readable Team: the Team, the key that made the request and its owner, the person or service account the request itself is owned by, the Agent, the deployment and the payer Team
keys.user.manage	On a request page reached through a key you own: that key, its Team and yourself
audit.read	The target of each readable audit event when it is a Team, key, service account, membership (the person), evaluator, dataset, score definition, experiment, rule, review queue, comparison, interpretation, role, management token, deployment, namespace or the Organization
evaluation.read	The person who started an experiment, created a dataset version or reviewed a queue item
evaluation.read, evaluation.content.read	The titles or external IDs of the cases offered for regrade or retry, which the dataset page already shows under the same permissions; a case whose fields are not readable keeps its dataset item identifier
team.members.manage	The Team's members and the directory groups that source their memberships; people.read is not needed
keys.user.create, keys.user.manage, keys.service.manage, keys.manage	The owner and the Team of each listed key, and in the New key review the names of the chosen models, tools, deployments and tool sets
approvals.decide	The requester and the Team of each approval to decide; a requester sees their own name on their own requests
deployment.access.manage	The people, Teams, directory groups and service accounts behind a deployment's existing access grants, active or not

Where no name is found, the identifier is shown as it is and nothing claims why. A name grants no access to the named item.

Membership and lifecycle

Role assignments identify the actual user and Organization membership instance, with an explicit Organization or Team scope. Team membership has source records: removing one direct/directory source does not end membership while another valid source remains. Final removal ends that instance. A later join creates a new instance; old user keys and old API owner grants do not revive.

SCIM/OIDC directory adapters reconcile real membership sources and scoped roles. They cannot grant organization.owner or clear manual administrator suspension. Ordinary service accounts are independent of their creator's employment. Suspending/revoking the service affects its keys; removing its creator does not.

Inference policy and private access

API operations include model.generate, model.embed, model.rerank, tool.invoke, deployment.invoke and telemetry.ingest. They are key operations, not management permissions. Effective resource access is catalog ∩ Team allowance ∩ key policy. Key expiry, current secret, status, owner, Team and budgets are checked independently.

A Chat audience authorizes new private application work without granting Team metadata. A Team Viewer is not automatically a Chat consumer. Private conversation ownership requires the exact user/current Organization membership; a Trace ID, Session ID, namespace or customer label cannot transfer it.

observability.read does not grant observability.content.read. Names, errors, events, previews and content search are sensitive content. Export needs observability.export and still obeys content authority. Own-key request reads do not authorize the complete shared Trace. There is no run.read or run.write permission.

Management tokens

Under account Access, a human can create an expiring mcm_… token with explicit permissions and scopes. It is an attenuation of current human authority, never an independent privileged service. The control listener rechecks the token and live membership; a token cannot gain its creator's broader unlisted permissions. Tokens cannot mint other tokens, and cannot perform inference. Reveal happens once; revocation is immediate at the next check.

See People and access, Team administration, management API and authentication.

Saving/importing a Tool validator version with evaluation.manage explicitly provisions or updates the Team's managed Evaluation execution key with the validated selected tool and retained allowed evaluator model/tool resources. The shared read-only policy permits configured Data and Decision tools only, within the Team allowance. This grant effect is audited; preflight and runtime do not widen or repair it. Human management permissions remain separate from inference key policy.

Executing validators or reading captured/enriched evidence requires evaluation.read, evaluation.content.read, evaluation.execute for execution, and both observability.read and observability.content.read in the same Team. Protected source reads recheck retention/deletion. Output-only assertions and ordinary saved-output templates retain their existing evaluation-content boundary. Metadata summaries and review/calibration values do not expose tool arguments, results or evidence-derived reasoning. See Protected evidence and tool validators.

Comparison case review uses the same permissions: evaluation.content.read reveals original input, expected behavior, protected source labels and answer text; evidence-consuming reasoning additionally needs current observability.read and observability.content.read and retained dependencies. evaluation.manage creates a fixed queue from selected terminal cases, including generation failures; evaluation.review records separate human scores. Numeric score access never grants protected reasoning or tool bodies. See Review and calibrate graders.

Explicit dataset sourceNamespace, externalId, title, tags and caseSettings are protected by evaluation.content.read, including user context and reasoning settings. evaluation.manage authors them, and existing agent.edit saves the optional dataset-context binding into a snapshot. This adds no role preset or inference authority; metadata-only readers retain opaque item identifiers.

Comparison groups and templates

Group readiness/launch requires Team evaluation.read, evaluation.execute, evaluation.content.read, agent.read and agent.test. Materializing model variants additionally requires agent.edit; existing permitted snapshots support test-only callers. The paginated subject catalog checks agent definition-content authority before reading model metadata and never searches another Team. Template creation/version edits use evaluation.manage; template listing and group summaries use evaluation.read, with private template drafts hidden unless evaluation.content.read is current. Request-key replays recheck current authority. Human role presets and virtual-key inference policy remain separate and unchanged. See Create and compare model runs.

Guided grader setup uses evaluation.manage to atomically create an optional score definition and complete first evaluator version. It adds no permission preset or inference authority. Sample testing requires the requester's current evaluation.read, evaluation.execute and evaluation.content.read; source-consuming graders and tool validators additionally require observability.read and observability.content.read. A sample retains the requester's membership and management-token restrictions rather than borrowing the original run starter's rights. Revocation stops new work; settlement of dispatched calls remains possible. See Create, test and calibrate graders.

Suite bundle upload/preview/commit requires existing Team evaluation.read, evaluation.manage and evaluation.content.read. Status is limited to the creating Organization membership with current evaluation.read; its safe result contains resource identities, not case/configuration bodies. Another member—including an administrator—does not adopt a private staging session by knowing its ID. Each request intersects the token with its owner's live permissions. Template references additionally need readable/testable saved snapshots; proposed model variants require agent.edit. Target model/tool allowances remain separate inference policy. Preview never provisions an identity or grants resources. Commit rechecks current permissions and publishes complete validated resources atomically. See Import a complete evaluation suite.

Agent publication and Live management

Review & publish derives automatic execution access from the saved model and tools on the server. deployment.publish remains independent of deployment.access.manage: first publication and actual policy/account/sharing changes require access-management authority, while an unchanged-access content update can be published without it. Existing presets gain no permissions from this flow. An explicit execution-policy save selects custom mode; an access manager must deliberately switch it back to automatic mode.

Live displays grant names under deployment.access.manage. API key readiness uses existing key-management visibility: general managers can inspect manageable owners; service-key managers can inspect service owners; own-key managers can inspect themselves. A caller outside that visibility reads Key status unavailable. The status reveals no key identifier or secret, and never grants authority to issue a key. Saved account defaults follow the Agent definition's existing content-read boundary. An account reference is not a reusable credential.