Service accounts
A service account is a non-human identity in your organization. It represents a machine, a CI workflow, or a coding agent.
A service account is assigned a set of permissions that define which API actions the service account's access tokens can take.
For a token to use on your own development machine, generate a personal access token instead. It carries your permissions and is revoked when you leave the organization.
Service accounts can be managed here.
Permissions
The permission selector groups permissions by resource. Every row is a single permission, identified by a resource:action key such as run:create or vault:unlock.
Only permissions a token could exercise through the API or the CLI are available.
Available permissions
| Resource | Key | What it allows |
|---|---|---|
| Runs | run:create | Trigger new runs. |
run:read | View run details, logs, and task outputs. | |
| Dispatches | dispatch:run | Trigger a dispatch. |
| Vaults | vault:read | View vault structure, settings, and activity. Does not reveal secret values. |
vault:create | Create new vaults. | |
vault:write | ||
vault:create_secret | Add secrets to the vault. | |
vault:update_secret | Edit, rotate, and remove secrets in the vault. | |
vault:create_var | Add vars to the vault. | |
vault:update_var | Edit and remove vars in the vault. | |
vault:unlock | Unlock the vault to access secrets in a run. | |
vault:manage | Manage vault settings and delete the vault. | |
| Images | image:push | Push container images to a registry using |
| Captain | captain:run | Submit test results to Captain. |
Some of these appear only when they're relevant to your organization, as abq:run requires ABQ, and captain:run requires Captain.
Vault permissions are broken out finely, so an account can get exactly the access it needs. It can read a vault's structure without seeing any values, or unlock a vault for a run without being able to change what's in it.
Coarser permissions grant finer ones
Selecting a coarse permission automatically grants the finer permissions it implies. For example:
run:creategrantsrun:read. You can't trigger a run without being able to read it.vault:writegrantsvault:create_secret,vault:update_secret,vault:create_var, andvault:update_var.- Every vault permission except
vault:creategrantsvault:read.
Implication only runs within a resource, and only downward. This nested hierarchy is illustrated in the UI via indentation.
Scoping vault permissions to specific vaults
Vault permissions can be granted org-wide or scoped to specific vaults.
When you select a vault permission that supports scoping, a Scope control appears with the ability to choose whether to apply the permission to all vaults or only specific ones.
Scoping is per permission, not per resource. A single service account can hold vault:read on every vault while holding vault:unlock on only the one vault its runs need.
You can only grant permissions you hold
A service account can't hold more authority than the person configuring it. When you create or edit an account, the selector reflects your own permissions.
For a scoped vault permission, you can only target vaults you hold that permission on yourself.
The same rule applies to removals: you can't take away a permission you don't have.
Access tokens
A service account can have multiple access tokens, which is helpful for rotating credentials. These credentials will default to a date-based name, but you can also give them more helpful names to describe where you intend to use them, for example.
RWX shows the token once, right after you create it. It starts with rwx_org_. Store it somewhere safe; it can't be shown again.
Revoking a token
Revoke a token from the service account's page. Revocation is immediate and permanent; issue a new token to replace it.
Deactivating a service account
Deactivating an account revokes all of its tokens and removes it from the list. Anything still using one of those tokens starts failing to authenticate, so confirm nothing depends on it first.