Access Roles
Control which applications and projects organization members can reach and manage.
Access roles control which applications and projects an organization member can reach and what they may manage inside those projects. They provide the project-scoped half of the organization permission model.
An access role does not grant vault-wide administration. Machines, alerts, members, billing, integrations, and other shared areas are controlled by the member’s vault role.
#How access roles work
Each organization member can hold one access role or no access role.
A member without an access role cannot reach any application or project.
Putting a project in scope gives the member view access to its Secrets, Machines, and Policies pages.
Management capabilities are configured separately for each scoped application or project.
Adding a target starts with all project-management capabilities enabled; disable the actions the role should not perform.
Access is resolved on each protected request, so edits affect every assigned member immediately.
This separation supports combinations such as a vault Admin with no project visibility, or a project operator with a minimal Collaborator vault role.
#View access is implicit
A project is visible when it falls inside the access role’s scope. The capability switches control management actions, not basic visibility.
If every capability is disabled for an in-scope project, the member receives a view-only project experience. They can open the project’s Secrets, Machines, and Policies pages but cannot perform the gated management actions.
A view-only scope is useful for auditors, reviewers, incident responders, and team members who need context without change authority.
#Project capabilities
Secrets
Capability | What it allows |
|---|---|
Normal secrets | Create and manage standard single-value secrets |
Structured secrets | Create and manage multi-field structured secrets |
Managed secrets | Create and manage externally synchronized or rotated secrets |
Canary secrets | Create and manage canary tripwires |
TTL secrets | Create and manage temporary, one-time human-recipient secrets |
Leased secrets | Create and manage on-demand temporary database credentials |
Secret permissions are separated by type. A role can manage standard and structured secrets without receiving authority over canaries, leased credentials, or temporary shares.
Machines
Capability | What it allows |
|---|---|
Add machines | Attach an existing machine to the project |
Remove machines | Detach a machine from the project |
Configure grants | Choose which project secrets an attached machine may read |
These permissions manage a machine’s relationship with the project. Vault-wide machine lifecycle actions, such as bootstrap, approval, disablement, and revocation, remain part of the vault role.
Access policies
Capability | What it allows |
|---|---|
Add and remove | Create or delete access policies and manage policy bindings |
Time window | Configure approved times and days |
IP allowlist | Configure policy-specific IP and CIDR restrictions |
Rate cap | Configure secret read-rate limits |
Co-sign | Configure the selected second-machine requirement |
TTL | Configure the policy lifetime control |
Each policy axis has its own capability. This lets a role manage one constraint without gaining authority to loosen every other constraint.
#Choose the scope
An access role uses either a broad scope or a specific scope.
Broad scope
Option | Projects included | Capabilities |
|---|---|---|
All applications and projects | Every application project and every standalone project, current and future | Full view and management |
All applications | Every current and future application and every project inside those applications | Full view and management |
All standalone projects | Every current and future standalone project | Full view and management |
A broad scope grants the complete capability set throughout the selected domain. Per-application and per-project capability settings do not apply while broad scope is selected.
Broad scopes include matching applications and projects created in the future. Use a specific scope when new resources should require an explicit permission decision.
Specific scope
Specific scope lets you select whole applications and individual standalone projects.
Application scope. Selecting an application includes all of its projects. The application’s capabilities become the baseline for those projects.
Inherited project. A child project uses the application baseline until you create a project-specific override.
Project override. Change the capability set for one child project while leaving the rest of the application unchanged.
Project exclusion. Remove one child project from an otherwise included application.
Standalone project. Select an individual standalone project and configure its own capabilities.
For example, a role can include an application, give its Development and Staging projects secret-management authority, make Production view-only through an override, or exclude Production completely.
#Create an access role
Open Organization → Access roles.
Select the plus button.
Enter a descriptive role name and an optional explanation of what it should reach.
Choose a broad scope, or leave broad access set to None and use the application and standalone-project picker.
For a specific scope, select an application or project and configure its Secrets, Machines, and Policies capabilities.
Review the scope summary and save the role.
Open Organization → Members and assign the role to the appropriate members.
Access roles are available for organization vaults on plans that include organizations. The current built-in vault-role configuration reserves access-role viewing and management for the vault owner.
Configure an application
Select the application in the scope tree.
Keep or adjust the default capabilities that should apply to all of its projects.
Expand the application to review its child projects.
Exclude any child project that should not be reachable.
Open an included child project to create a different capability set when it should not inherit the application baseline.
Configure a standalone project
Select the standalone project in the scope tree.
Open the selected project’s capability panel.
Disable any secret types, machine actions, or policy controls the role should not manage.
Leave every capability disabled when the project should be view-only.
#Assign an access role
Access roles are assigned after a person has joined the organization. Invitations pre-assign a vault role, while project access is chosen from the member table once the membership exists.
Open Organization → Members.
Find the member.
Open the Access role selector in the member’s row.
Choose an active access role, or select None to remove all project access.
Save the member changes.
The member’s dashboard navigation and project actions refresh after assignment. The role change is recorded in the Audit Log.
Assigning None removes access to every application and project, even if the member’s vault role remains unchanged.
#Editing a role
Editing an access role changes the effective project access of every member assigned to it.
Adding an application or standalone project makes it available to all assigned members.
Removing or excluding a project removes it from their project list.
Disabling a capability preserves view access but blocks that management action.
Changing an application baseline affects inheriting child projects but not projects with an explicit override.
Switching to a broad scope replaces the specific scope and grants full capabilities across the chosen domain.
Use a separate access role when two groups need different long-term scopes. This keeps future changes predictable and avoids repeatedly editing one shared definition for unrelated teams.
#Archive, restore, or delete an access role
Archive. Removes an unused role from active assignment and editing while preserving it for later restoration.
Restore. Returns an archived role to active use.
Delete. Permanently removes the role and its current scope and grants.
Reassign first. A role cannot be archived or deleted while organization members are assigned to it.
Archived roles are read-only until restored. Their recorded permission history remains available for auditing even after permanent deletion.
#Common access-role patterns
Role pattern | Suggested scope | Suggested capabilities |
|---|---|---|
Project auditor | Selected applications or standalone projects | All capabilities disabled for view-only access |
Application developer | One application | Normal and structured secrets; required machine actions; limited policy controls |
Production operator | A production application scope with deliberate overrides | Only the secret types, machine actions, and policy axes needed for operations |
Security engineer | Sensitive projects | Canary secrets and selected policy controls, with other secret types disabled |
Database credential operator | Projects using leased credentials | Leased secrets and only the machine or policy controls required for the workflow |
#Recommended access design
Start with specific scope unless the member truly needs every current and future resource in a domain.
Use application inheritance for consistent environments, then make Production stricter with an override or exclusion.
Keep view-only projects in scope with every capability disabled.
Separate secret types so specialized credentials and canaries remain restricted.
Review access roles when applications, environments, or team responsibilities change.
Use the Audit Log to review access-role creation, edits, assignments, archival, restoration, and deletion.