Permissions

A permission enables an identity or an access token to take the action that corresponds to the permission. The same permission governs the action wherever you take it, in the web app or through the API and the CLI.

  • A member of your organization holds permissions through the groups they belong to.
  • A service account holds a set of permissions, and its access tokens inherit them.
  • A personal access token holds a set of permissions derived from the ones you hold.

Permission keys

Every permission is identified by a resource:action key, such as run:create or vault:unlock.

Available permissions

The last two columns name the surfaces each permission governs.

ResourceKeyWhat it allowsAPI/CLIWeb
Organizationorg:manage

Full organization administration. Manage members, billing, settings, and organization-managed infrastructure.

❌✅
Groupsgroup:createCreate new groups.❌✅
group:manage

Edit a group's permissions, members, and nesting, and delete the group. A manager can add themselves to the group, so this also grants everything the group grants.

❌✅
Service accountsservice_account:createCreate new service accounts.❌✅
service_account:manage

Edit a service account's permissions, issue its access tokens, and attach it to a vault.

❌✅
Runsrun:createTrigger new runs.✅❌
run:manageCancel and re-run existing runs.❌✅
run:readView run details, logs, and task outputs.✅✅
Cron schedulescron:runManually trigger a cron schedule.❌✅
cron:managePause, resume, and snooze cron schedules.❌✅
Dispatchesdispatch:runTrigger a dispatch.✅✅
dispatch:manageArchive dispatch definitions.❌✅
Concurrency poolsconcurrency_pool:manage

Pause and resume concurrency pools and abandon their leases.

❌✅
Vaultsvault:createCreate new vaults.✅✅
vault:write

Add, update, and remove secrets and vars in the vault.

✅✅
vault:create_secretAdd secrets to the vault.✅✅
vault:update_secretEdit, rotate, and remove secrets in the vault.✅✅
vault:create_varAdd vars to the vault.✅✅
vault:update_varEdit and remove vars in the vault.✅✅
vault:unlock

Unlock the vault to access secrets in a run.

✅❌
vault:approve_accessApprove another user's request to access the vault.❌✅
vault:manageManage vault settings and delete the vault.✅✅
Imagesimage:access

Push container images built in RWX to a registry with rwx image push. Pull them directly from RWX with rwx image pull.

✅❌
Organization Notificationsnotification:createCreate organization notification subscriptions.❌✅
notification:manageEdit and delete organization notification subscriptions.❌✅
Webhookswebhook:manage

Pause, resume, and delete webhooks and manage their tokens.

❌✅
VCS integrationsvcs_integration:createConnect new version control integrations.❌✅
vcs_integration:manageConfigure and disconnect version control integrations.❌✅
Captaincaptain:runSubmit test results to Captain.✅❌
Teststests:manage

Manage test suite settings: branches, quarantine policy, visibility, and file timings.

❌✅
tests:quarantineQuarantine and unquarantine flaky tests.❌✅
Billingbilling:manage

Open the billing portal to read invoices and manage payment methods.

❌✅

Coarser permissions grant finer ones

A coarse permission automatically grants the finer permissions it implies. For example:

  • run:manage grants run:create. run:create grants run:read, and run:read grants run:public_read.
  • cron:manage grants cron:run.
  • dispatch:manage grants dispatch:run.
  • tests:manage grants tests:quarantine.
  • vault:write grants vault:create_secret, vault:update_secret, vault:create_var, and vault:update_var.

vault:manage does not grant vault:create. A holder can reconfigure and delete existing vaults without being able to add new ones.

A permission never grants a permission on another resource. org:manage is not a catch-all: a member of the admin group holds each resource's managerial permission directly.

Scoping permissions to specific resources

Some permissions can be applied to all instances of a resource or only to specific ones:

  • Every vault permission except vault:create.
  • group:manage, for specific groups.
  • service_account:manage, for specific service accounts.
  • notification:manage, for specific notifications.
  • vcs_integration:manage, for specific integrations.

A single holder can have different permissions across different vaults.

You can only grant permissions you hold

What you grant is limited to the permissions you have yourself. For a scoped permission, you can only target the resource instances you hold that permission on.

Two permissions carry the ability to grant others:

  • vault:manage on a vault lets you grant vault:unlock and vault:approve_access on that vault without holding them.
  • group:manage can only be granted by someone who holds everything the group grants. See groups.