# auth.md

This describes how AI agents and automated tools authenticate to CircleCI's API and pipelines.

## Identity

CircleCI accounts are backed by your VCS identity: sign in via OAuth with GitHub, GitLab, or Bitbucket. There is no separate CircleCI username and password.

## API credentials

- **Personal API token** (recommended): scoped to your user, generated at https://app.circleci.com/settings/user/tokens. Send it as `Authorization: Bearer <token>` on API v3 (recommended), or in the `Circle-Token` header / as the HTTP Basic Auth username with blank password on API v2. Tokens created manually inherit the full read/write permissions of the creating user. For a scoped, user-delegated token (Read, Write, or Admin), register via OAuth 2.0 Dynamic Client Registration (see Registration).
- **Project API token**: scoped to a single project, generated in Project Settings. Supported on the legacy API v1 only; not supported on API v2 or v3.

CircleCI's current API is **v3** (base `https://circleci.com/api/v3`), where new capabilities land. API **v2** (base `https://circleci.com/api/v2`) remains supported.

Example (API v3, recommended):

    curl --header "Authorization: Bearer $CIRCLE_TOKEN" \
      "https://circleci.com/api/v3/users?filter[user_id]=me"

API v2 remains supported and offers a convenience current-user route:

    curl --header "Circle-Token: $CIRCLE_TOKEN" https://circleci.com/api/v2/me

## OIDC for running jobs

CircleCI issues OpenID Connect ID tokens (`CIRCLE_OIDC_TOKEN`, `CIRCLE_OIDC_TOKEN_V2`) to jobs at runtime, letting a job authenticate to AWS, GCP, or HashiCorp Vault without storing long-lived cloud credentials. This is outbound: it authenticates a CircleCI job to a third-party service, not a caller to CircleCI.

- Discovery document: https://oidc.circleci.com/.well-known/openid-configuration
- JWKS: https://oidc.circleci.com/.well-known/jwks-pub.json
- Guide: https://circleci.com/docs/guides/permissions-authentication/openid-connect-tokens/

## Registration

Agents and tools can register via **OAuth 2.0 Dynamic Client Registration** (RFC 7591) to obtain a scoped, user-delegated token, no pre-shared secret required:

- **Register**: `POST https://app.circleci.com/oauth/register` (no auth header; returns a `client_id`, no client secret)
- **Authorize**: https://app.circleci.com/oauth/authorize (PKCE; the user picks Read, Write, or Admin scope)
- **Token**: https://app.circleci.com/oauth/token

Scopes are ceilings bounded by the authorizing user's role. Tokens issued this way are 90-day personal API tokens valid on API v2 and v3. Guide: https://circleci.com/docs/guides/toolkit/oauth-dynamic-client-registration/

Alternatively, any authenticated user can create a personal API token manually at https://app.circleci.com/settings/user/tokens with no approval step.

## Reference

- API v3 reference (recommended): https://circleci.com/docs/api/v3/index.md
- API v2 authentication: https://circleci.com/docs/api/v2/index.html
- OAuth 2.0 Dynamic Client Registration: https://circleci.com/docs/guides/toolkit/oauth-dynamic-client-registration/
- OIDC tokens in jobs: https://circleci.com/docs/guides/permissions-authentication/openid-connect-tokens/