OAuth Token Exchange: short-lived API tokens from your identity provider

Buildkite now supports OAuth 2.0 Token Exchange (RFC 8693), letting you mint short-lived Buildkite API tokens on behalf of your user directly from your identity provider (IdP). Instead of managing long-lived API tokens, your identity provider tooling can exchange a signed JWT for a scoped, time-limited Buildkite token — no secrets to store, rotate, or worry about leaking.

How it works

First, set things up once: generate a keypair in your infrastructure, keep the private key with your tooling for signing JWTs, and publish the public key on a JWKS (JSON Web Key Set) host. Then register a token exchange application in your Buildkite organization settings, point it at your JWKS (inline or via URI), and configure the grantable scopes, maximum TTL, and any IP restrictions for minted tokens.

From there, each token exchange follows three steps:

1. Your tooling signs a JWT with its private key and sends it to Buildkite's /oauth/token endpoint.
2. Buildkite fetches your JWKS to verify the JWT's signature against your published public key.
3. Buildkite mints a short-lived bktx_ token scoped within the limits of your token exchange application and returns it to your tooling. Every mint is recorded in the audit log against the application, user, and key ID.

curl -X POST https://api.buildkite.com/v2/oauth/token \
  -d grant_type=urn:ietf:params:oauth:grant-type:token-exchange \
  -d client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer \
  -d client_assertion=$SIGNED_JWT \
  -d audience=your-org-slug \
  -d subject_token=$USER_EMAIL \
  -d subject_token_type=urn<img class="emoji not-prose size-4 inline align-[-0.1em]" title="buildkite" alt=":buildkite:" src="https://buildkiteassets.com/emojis/img-buildkite-64/buildkite.png" draggable="false" />params:oauth:token-type:user-email \
  -d scope="read_builds read_pipelines"

Key details

• Short-lived by design: Tokens expire automatically based on the TTL you configure (or request per-exchange), so leaked credentials are already expired.
• Scoped access: Each token exchange application defines grantable and default scopes, and callers can request a subset per token.
• IP restrictions: Lock down token exchange requests and minted tokens to specific source IP ranges.
• Full audit trail: Every token minted is logged as an audit event, tied to the token exchange application, user, and public key ID.
• JWT private key rotation support through JWKS URI: Point to your IdP's hosted JWKS endpoint and Buildkite will fetch and cache public keys associated with your JWT private key automatically, including support for key rotation.
• Rate limited: Organization-level rate limiting protects against abuse.

OAuth Token Exchange is available on Enterprise plans. To get started, see the OAuth Token Exchange docs, visit your organization's settings, or reach out to your account team.