Roles and permissions
The 41 permissions and the 7 built-in roles, and where a grant lands.
Path: Settings > Roles
A role is a named set of permissions. A grant attaches one role to one person or machine identity at one scope.
Permissions
41 permissions, each resource:action. We never store an editor wildcard, so a permission we add later never widens an existing role.
| Group | Permissions |
|---|---|
| Secrets | secret:read, secret:reveal, secret:write, secret:delete |
| Projects | project:read, project:create, project:update, project:delete |
| Environments | environment:read, environment:create, environment:update, environment:delete |
| Machine Identities | machine:read, machine:create, machine:issue, machine:revoke |
| Members | member:read, member:invite, member:remove, member:role_assign |
| Roles | role:read, role:manage |
| Single sign-on | sso:read, sso:manage |
| Integrations | integration:read, integration:connect, integration:configure, integration:run, integration:delete |
| Dynamic Secrets | dynamic:read, dynamic:configure, dynamic:generate, dynamic:revoke |
| Audit Log | audit:read, audit:export |
| Billing | billing:read, billing:manage |
| Organization | org:read, org:update, org:delete |
| Developer Apps | app:manage |
Built-in roles
We seed these into every workspace; you cannot edit them.
| Role | For | Permissions |
|---|---|---|
| Owner | Person | All 41 |
| Admin | Person | All except org:delete |
| Developer | Person | Day-to-day work on values, projects, environments and identities, plus member:read, role:read, integration:read, integration:run, dynamic:read, dynamic:generate, audit:read, org:read |
| Viewer | Person | Every :read permission |
| Billing Admin | Person | billing:read, billing:manage, org:read |
| Secrets Reader | Machine | secret:read, secret:reveal, dynamic:generate |
| Secrets Writer | Machine | Secrets Reader plus secret:write, secret:delete |
We derive Viewer from the catalog; secret:reveal is not a read permission, so Viewer never holds it. The first person in a new workspace receives Owner.
Owner-only actions
You must be a workspace owner; no permission grants these.
- Connect your own encryption key (Encryption and BYOK)
- Connect an audit log destination (Audit Log)
- Change the two-factor requirement (Security and MFA)
Custom roles
| Route | Purpose |
|---|---|
/settings/roles | Built-in roles; ?tab=custom lists your custom roles. Each tab lists roles For members and For machine identities, with how many of the 41 permissions each holds and how many grants use it |
/settings/roles/new | Clone a built-in role and uncheck permissions; you can select only permissions you hold |
/settings/roles/[roleId] | A built-in role, read-only, with Duplicate. A custom role opens the editor with role:manage, read-only without. Both show the type, the permission count, the grants (with a link to Members or Machine Identities) and the role it was cloned from |
Unavailable on Free (Billing and plans): the Custom tab and /settings/roles/new say so and link to the upgrade.
You cannot grant more than you hold. The picker hides roles carrying a permission you lack at that scope; we re-check on submit, since a form post bypasses the picker.
Grant scopes
| Scope | Granted on | Reaches |
|---|---|---|
| Workspace | Settings > Members | Everything in the workspace |
| Project | The project's Access page | The project and every environment in it |
| Environment | The project's Access page | That one environment |
We derive an environment's parent project instead of trusting the form, so a project grant never authorizes another project's environment. A check naming an environment also matches a grant on its parent.
Required permissions
Step-up rules: Security and two-factor.
| Action | Permission | Step-up | Audit entry |
|---|---|---|---|
| Open the roles list or a role | role:read | No | none |
| Create a custom role | role:manage | Two-factor and fresh | role.created |
| Edit a custom role | role:manage | Two-factor and fresh | role.updated |
| Delete a custom role | role:manage | Yes | role.deleted |
| Grant a role | member:role_assign at that scope | Two-factor and fresh | role.assigned |
| Revoke a grant | member:role_assign at that scope | No | role.unassigned |
You can't grant yourself a role. Access you hold through elevated access lets you act, but you can't hand it on: a grant, an invitation, a custom role or a machine identity can carry only what you hold without it.
No role.* entry appears in the Audit Log action filter.
Next: Single sign-on.