Service accounts and API keys
Your CI job is authenticating with a key that belongs to an engineer. That engineer leaves, their account is removed, and the build breaks at 2am. You can see this coming, so do not set it up that way.
Use a service account for anything that outlives one person, and keep personal keys for your own scripts.
Two kinds of owner
| Owner | Use it for | Where you create keys |
|---|---|---|
| You | Your own scripts and local tools | Settings › API |
| Service account | CI, Terraform and MCP clients | Settings › Members, then Service accounts |
The rule that matters: a key never does more than its owner can do at the moment it is used. Reduce the owner's access and the key shrinks with it. Remove the owner, and the key stops working.
Create a service account
You need service_accounts:create.
- Open Settings › Members, then Service accounts, and choose New service account. Create one for each pipeline or tool.
- Add it to a group. Until it joins a group, it has no access. The built-in CI pipeline role fits most pipelines.
- Create a key for it, using the steps below.
Service accounts join groups like people do, but sign in only with their own API keys.
Create an API key
Creating a key needs a signed-in person. An API key cannot create another API key, so a leaked key cannot quietly mint a replacement for itself.
- Choose Create key.
- Name it after where it will live, for example
CI (GitHub Actions). You will be glad you did on the day you need to revoke it. - Choose Permissions, using a preset or a custom list.
- Choose Organizations: All, or Selected. An organization includes its children.
- Choose Expires: 30, 90, 180 or 365 days. The default is 90.
- Create the key, and copy the secret.
What you should see
The secret is shown once and cannot be retrieved later. If you lose it, revoke the key and create a new one. The list only ever shows its prefix, what it may do, its organizations, its expiry and when it was last used.
The key looks like dwc_<id>_<secret>. Send it as a bearer token, as the REST API page shows.
Presets
| Preset | Permissions | Use it for |
|---|---|---|
| Read only (MCP) | 19 permissions that read findings, resources, scans, integrations and more | Dashboards, reporting scripts and read-only MCP clients |
| CI pipeline | findings:read, guard.events:read, guard.policies:read, reports:download, resources:create, resources:read, scans:read, scans:run | Pipelines that run scans and read results |
| Custom | Exactly what you pick | Anything narrower |
Start with Read only (MCP) and add to it when something fails. Custom keys can only use permissions you hold and that are allowed on keys at all. Permissions marks which those are.
Revoke a key
Choose Revoke on the key's row. You can revoke your own keys, and anyone with api_keys:revoke can revoke anybody's.
Anything still using that key stops working immediately, and this cannot be undone. Deleting a service account does the same to all of its keys, while its past activity stays in the audit log.
Try this next
Look at Settings › API and sort by Last used. A key nobody has used in months is a risk with no benefit, so revoke it. Then create a Read only (MCP) key and call the REST API with it.