OAuth 2.0 API Access with Dynamic Client Registration

CircleCI APIs now support OAuth 2.0 authorization code flow with Dynamic Client Registration (DCR).

Tools and integrations can now authenticate to CircleCI APIs using standard OAuth 2.0 — no manually issued client secrets required. The new flow issues a 90-day Personal Access Token (PAT) that works with all existing CircleCI API v2 endpoints, accepted as either a Bearer or Circle-Token header.

What’s new

Dynamic Client Registration — Any tool can register itself as an OAuth client at runtime with a single unauthenticated POST /oauth/register request. No approval process, no static credentials to manage.

Authorization Code + PKCE — The flow uses mandatory PKCE (S256), eliminating the need for a client secret entirely. This makes CircleCI OAuth safe for native apps, CLIs, and local tooling where a secret cannot be kept confidential.

Scoped access — During the authorization consent screen, users choose the access level to grant the requesting tool: Read, Write, or Admin. These scopes narrow what the token can do — they cannot escalate privileges beyond what the authorizing user already holds in CircleCI.

Standard discovery — All endpoints are published at https://app.circleci.com/.well-known/oauth-authorization-server, making the server compatible with any RFC 8414-aware OAuth library.

Pushed Authorization Requests (PAR) — For clients that want additional request integrity, CircleCI also supports RFC 9126 PAR via POST /oauth/par.

Automatic token rotation — Re-running the authorization flow for an existing client_id atomically revokes the previous token and issues a new one. No manual revocation step needed.

How it works

1. Register your client once at POST /oauth/register to receive a client_id.
2. Generate a PKCE verifier/challenge pair and open the authorization URL in a browser.
3. The user selects an access level (Read, Write, or Admin) and clicks Allow. The granted scope is capped at the user’s own CircleCI permissions — users cannot grant a tool more access than they have.
4. Exchange the returned authorization code for a 90-day PAT at POST /oauth/token.
5. Use the token as a standard Bearer token on any CircleCI API v2 call.

Tokens expire after 90 days (7,776,000 seconds). There is no refresh token — re-run the authorization flow to rotate.

Getting started

See the Circle Documentation for a complete walkthrough with copy-pasteable curl commands and a local Python listener that handles the redirect callback automatically.

What’s Next

Refresh for the Oauth. Right now the tokens have a long expiration and you need to generate a new one. We do have plans to support refresh, when we do the expiriation window for oauth will be much smaller.

Giving Orgagnization administrators greater visibility and control over Oauth and Personal Access Tokens. We know this is currently a limit and understand administrators what controls and visibility.