How do you apply least privilege to CircleCI tokens and secrets?

Least privilege on CircleCI means using the narrowest token that works, giving personal tokens an expiry, restricting contexts to the groups that need them, and replacing stored cloud keys with OIDC tokens issued per job. Then rotate and delete what you no longer use.

Which token types exist, and how broad are they?

CircleCI documents two kinds of API token. Personal API tokens created in the web app grant full read and write permissions, and they expire on a date you choose, no more than one year ahead. Project API tokens are scoped to a project, with three options: Status, Read Only and Admin. Status tokens only read build status, which is what a README badge needs. Tokens cannot be edited after creation, so changing a scope means deleting and recreating, which the docs call rotation.

Because a manual personal token is all-powerful for the person who owns it, it is the one to avoid in automation. A script that only reads build status should use a Status project token, not a developer's personal token. A constructed example: a dashboard polls pipelines with the lead engineer's personal token. When she leaves, the token is deleted with her account and the dashboard breaks, which at least ends the exposure. If she had not left, a leak of that token would have given full API access under her identity.

How do contexts limit secrets?

Contexts hold environment variables for jobs. CircleCI says a newly created context has security set to All members, meaning anyone in your organization can access it at runtime. Organization members can create contexts, but only organization administrators can restrict them using security groups, with an exception for Bitbucket organizations. A workflow must meet any restrictions on the context to use it.

So the default is broad. Split secrets by purpose, for example a staging deploy context and a production deploy context, and restrict the production one to the group that approves releases.

Why prefer OIDC over stored keys?

CircleCI provides OpenID Connect ID tokens to jobs as environment variables so jobs can reach compatible cloud services without long-lived credentials stored in CircleCI. The docs list less exposure of stored credentials and simpler credential management. You configure your cloud service to trust CircleCI as an identity provider, then scope the cloud role by claims in the token.

For forked builds, the docs say OIDC tokens are generated only if the setting that passes secrets to builds from forked pull requests is enabled. Leave that off for public repositories unless you know why you need it.

How should you handle secrets on the command line?

CircleCI's guidance on secure secrets handling lists risks: command history, process arguments visible to other users, system logs, console output and unencrypted files on disk. It suggests the CircleCI CLI, which prompts for secrets instead of taking them as arguments, and avoiding env and printenv which print every variable.

What to do

1. List every personal and project API token. Delete any you cannot attribute to a current use.
2. Replace personal tokens in automation with project tokens at the lowest scope that works.
3. Set expiry on every personal token and track the notification emails, which arrive 30, 15, 7 and 1 day ahead.
4. Review contexts. Restrict production contexts with security groups and remove All members from sensitive ones.
5. Move cloud access to OIDC and delete the stored cloud keys after you verify the new path.
6. Check the fork secrets setting on public projects.
7. Scan the pipeline config and repository for committed credentials. Safeguard's secrets scanning and policy gates can enforce this on pull requests.

Quick check

Sources

1. CircleCI: Managing API tokens
2. CircleCI: Using contexts
3. CircleCI: OpenID Connect tokens
4. CircleCI: Secure secrets handling

Last reviewed: 18 October 2026.