Roles

For any enterprise or its workspaces, roles determine what its members can do. Customize your own or use the built-in roles predefined.

Roles define what members can do within your enterprise and its workspaces. In addition to the built-in roles, you can create custom roles with granular permissions tailored to how your organization operates.

Two scopes: enterprise and workspace

Roles exist at two levels, and the two sets of roles are distinct.

• Enterprise roles govern access to enterprise-wide settings, billing, members, and the catalogs of shared resources (rulesets, tools, models, templates, and more).
• Workspace roles govern access within a single workspace: its code, compliance state, docs, and membership.

Each member has one role at the enterprise level. Within an individual workspace, a member can be assigned a different role that applies only there. A member who is an enterprise Viewer might be a workspace Admin in the one workspace they own, for example.

Built-in enterprise roles

Five roles are available by default at the enterprise level.

Owner has every enterprise permission. Only an Owner can delete the enterprise or grant the Owner role to someone else.

Admin has every enterprise permission except deleting the enterprise, and cannot assign the Owner role. In practice an Admin runs day-to-day administration: managing members and teams, configuring agents, tools, models, integrations, and secrets, and, because the permission domains were recently broadened, approving staged ruleset changes (enterprise.rulesets.approve) and compliance overrides (enterprise.compliance.approve), not just viewing them.

Billing Admin is a finance-focused role. It can view and manage billing, manage payment methods, and view usage, plus see the member list and browse the templates and modules catalogs so spend can be reconciled against who and what is consuming it. It has no access to enterprise settings, agent or tool configuration, secrets, or integrations.

Member is the standard role for people doing the work. A Member can create workspaces and has read access across most enterprise areas (members, teams, usage, rulesets, compliance, workflows, tools, models, subagents, agent configuration, integrations, settings, secret names, templates, and modules) but cannot change enterprise-level configuration. This role replaces the legacy "Editor" enterprise role; existing Editors are migrated to Member automatically.

Viewer is read-only and cannot create workspaces. It can see the member list, teams, usage, compliance state, and the templates and modules catalogs.

Built-in workspace roles

Four roles are available by default within a workspace.

Owner has every workspace permission and is typically the person who created the workspace.

Admin has every workspace permission except deleting the workspace. Admins manage settings, the target branch, membership, rulesets, compliance, tools, workflows, secrets, subagents, and docs.

Editor can do the work without changing how the workspace is governed: view and edit content (Terraform code, canvas, plans and applies), manage docs, view and trigger compliance evaluations and submit overrides (workspace.compliance.manage), and view rulesets, tools, workflows, secret names, subagents, members, and settings. Editors cannot change settings, manage membership, or approve ruleset or compliance changes.

Viewer has read-only access: view content, rulesets, compliance, tools, workflows, subagents, docs, members, and settings.

Permission domains

Permissions are the individual capabilities that make up a role. Each permission belongs to a domain (a feature area), and most domains expose a view permission plus one or more management actions (manage, approve, create, delete).

Enterprise permissions are organized into these domains:

Workspace permissions are organized into these domains: settings, members, content, rulesets, compliance, tools, workflows, secrets, subagents, and docs.

The rulesets and compliance domains exist at both scopes and each carry three actions: view, manage, and approve. The approve action is separate on purpose: a member can be allowed to draft a ruleset or submit a compliance override without being allowed to approve it. See Rulesets and Compliance for what those areas govern.

Custom roles

Custom roles let you define exactly what a member can and cannot do. Instead of fitting everyone into one of the built-in roles, you can create roles that match the way your teams actually work.

To create a custom role, go to your enterprise settings and navigate to the Roles section. Give the role a name, a description, and then select the permissions it should have from the domains above. A role can hold any combination of permissions, so you can make it as broad or as narrow as you need.

For example, you might create a "Security Reviewer" role that can view all workspaces and manage and approve rulesets but cannot edit content or change enterprise settings. Or a "Tool Administrator" role that can configure MCP servers (tools.manage) and manage secrets but has no access to billing or member management.

Custom roles appear alongside built-in roles when you invite members or change someone's role, and they work the same way at both the enterprise and workspace level.

Assigning roles

Roles are assigned when you invite a member or from the People page in your enterprise settings.

Role assignment is bounded by what the assigner already holds: you can only grant a role whose permissions are a subset of your own. This prevents privilege escalation: a member with members.roles.assign cannot promote someone into a role that holds permissions the assigner lacks. It is also why only an Owner can grant the Owner role.

Access tokens

The same permission catalog is used by enterprise access tokens, so any permission you can grant to a role can also be stamped onto a token for CI or automation use. Scope tokens to the narrowest set of permissions the job requires.

Best practices

• Start with built-in roles and create custom roles only when the defaults do not match your access requirements.
• Use Billing Admin for finance staff rather than granting full Admin just to manage the subscription.
• Separate approve from manage on rulesets and compliance when you want a review step, so one role drafts changes and another approves them.
• Name roles after their function, not after teams or individuals. "Security Reviewer" is more durable than "Sarah's Role".
• Keep the number of custom roles manageable. A handful of well-defined roles is easier to maintain than dozens of highly specific ones.
• Review permissions periodically as your organization's needs change.