Project API Token permission scoping and credential lifecycle

Answer to the Core Questions

1. Can Project API tokens be restricted to read‑only or write‑only actions? No. The token payload does not contain a scope field; once issued it can call any project‑level API endpoint that the bearer has permission to use. Permission granularity is not exposed at the token level in CircleCI’s public API or UI.

2. Is there a documented method to enforce a mandatory expiration date on these tokens without manual deletion? No. CircleCI does not provide a TTL or auto‑rotation feature for Project API tokens. Expiration must be handled by revoking the token (via the UI or the API) and creating a new one, typically orchestrated by an external secret‑management workflow.

Why Project Tokens Lack Granularity

• Project tokens are intended to isolate project namespaces, not to enforce fine‑grained access control.
• All endpoints that operate on a project share the same permission set; the API does not differentiate read vs. write at the token level.
• CircleCI’s documentation and API schema for tokens (/api/v2/token) show only id, name, created_at, and expires_at (if set manually), but no scope flags.

Managing Expiration and Rotation

Because there is no built‑in expiration, teams usually adopt one of the following patterns:

• External Secret Manager Rotation: Store the token in a vault (e.g., HashiCorp Vault, AWS Secrets Manager). Use the vault’s rotation policy to delete the old token and generate a new one via CircleCI’s API.
• Automated Revocation Script: Periodically run a script that lists all tokens for a project, checks their age, and deletes those older than a threshold. Example using curl:

  curl -X GET "https://circleci.com/api/v2/project/${VCS}/${ORG}/${REPO}/token" \
    -H "Circle-Token: ${CIRCLECI_PERSONAL_TOKEN}" \
    | jq '.items[] | select(.created_at < "$(date -u -d "-30 days" +%Y-%m-%dT%H:%M:%SZ)") | .id' \
    | xargs -I{} curl -X DELETE "https://circleci.com/api/v2/token/{}" \
    -H "Circle-Token: ${CIRCLECI_PERSONAL_TOKEN}"
  

• Manual Cleanup: Use the CircleCI UI to delete tokens that are no longer needed. This is simple but relies on human oversight.

Practical Steps for a Least‑Privilege Workflow

1. Create a dedicated project token for each environment (dev, staging, prod). Keep the token names descriptive.
2. Store each token in a secret manager that supports automatic rotation or scheduled revocation.
3. Configure your CI/CD pipeline to fetch the token at runtime, ensuring the token is never hard‑coded in the repository.
4. Set a rotation policy (e.g., every 30 days) and monitor for failed builds that may indicate a revoked token.
5. When a token is rotated, update the secret manager and verify that downstream services (e.g., deployment scripts) can still authenticate.

What to Do Next

Because token scoping and expiration are not available natively, the most effective approach is to treat the token as a short‑lived secret managed outside of CircleCI. If you need finer access control, consider using CircleCI’s Personal Access Tokens with scope flags, but note that those are not project‑isolated and may expose broader access.

Could you confirm which CircleCI plan you are using (Free, Pro, Enterprise)? The token capabilities and available API endpoints can vary slightly between tiers, and that may affect the exact rotation strategy you can implement.