Roles and permissions
The 36 permissions and the 7 built-in roles, and where a grant lands.
Settings then Roles lists what each person and machine may do. A role is a named set of permissions. A grant attaches one role to one person or one identity, at the workspace or at a project or a single environment.
The 36 permissions
Every slug is resource:action. Wildcards exist in the editor as shorthand and are never stored, so adding a permission can never quietly widen a role somebody already holds.
| Group | Permissions |
|---|---|
| Secrets | secret:read, secret:reveal, secret:write, secret:delete |
| Projects | project:read, project:create |
| Environments | environment:read, environment:create |
| 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 |
The 7 built-in roles
They are seeded into every workspace and cannot be edited. A custom role is made by cloning one.
| Role | Given to | What it holds |
|---|---|---|
| Owner | A person | All 36 |
| Admin | A person | All except org:delete |
| Developer | A 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 and org:read |
| Viewer | A person | Every :read permission |
| Billing Admin | A person | billing:read, billing:manage, org:read |
| Secrets Reader | A machine | secret:read, secret:reveal, dynamic:generate |
| Secrets Writer | A machine | Those, plus secret:write and secret:delete |
Viewer is derived from the catalog rather than listed by hand. secret:reveal is not a read permission, so it can never fall into Viewer by accident.
The first person in a new workspace gets Owner rather than Admin, so every workspace has somebody who can delete it.
Some actions carry no permission slug at all. These ask whether you are the workspace owner instead:
- connecting your own encryption key
- connecting a destination for the record
- changing the two-factor requirement
- deleting the workspace
Custom roles
/settings/roles/new clones a built-in role and lets you uncheck what you do not want. Only permissions you hold yourself are selectable. /settings/roles/[roleId] edits the name and the description afterward, along with the matrix. A built-in role answers 404 there.
Free allows 0 custom roles, so the page is unreachable on that plan. Pro and Enterprise allow as many as you like.
Nobody can grant more than they hold. The picker hides a role carrying a permission you lack at that scope, and the server checks again, because a form post goes around the picker.
Where a grant lands
| Scope | Where you grant it | What it reaches |
|---|---|---|
| Workspace | Settings then Members | Everything in the workspace |
| Project | The project's Access page | That project and every environment in it |
| Environment | The project's Access page | That one environment |
An environment's parent project is derived rather than taken from the form, so a grant on one project cannot authorize an environment in another. A check naming only an environment still finds a grant held on its parent.
There is no separate production unlock. Reading production is a role scoped to that project or that environment.
What each action needs
| Action | Needs | Confirm it is you | Recorded as |
|---|---|---|---|
| Open the roles list | role:read | No | not recorded |
| Create a custom role | role:manage | No | role.created |
| Edit a custom role | role:manage | No | role.updated |
| Delete a custom role | role:manage | No | role.deleted |
| Grant a role at any scope | member:role_assign at that scope | No | role.assigned |
| Revoke a grant | member:role_assign at that scope | No | role.unassigned |
None of the role.* entries appears in the action picker on the Audit Log page, and role has no family of its own there. Narrow by actor and date, then export. See browsing the record.