OAuth token exchange

How it works

┌────────────┐    1. JWT assertion    ┌──────────────┐
│            │ ─────────────────────▶ │              │
│  Your app  │                        │ Buildkite    │
│            │ ◀───────────────────── │ /oauth/token │
│            │    2. bktx_ token      │              │
│            │                        └──────────────┘
│            │    3. Bearer bktx_...  ┌──────────────┐
│            │ ─────────────────────▶ │ Buildkite    │
│            │ ◀───────────────────── │ REST/GraphQL │
└────────────┘    4. API response     └──────────────┘

1. Sign a JWT assertion (RFC 7523) with your RSA or ECDSA private key.
2. Exchange the assertion at POST /oauth/token for a short-lived Buildkite API token (prefixed bktx_).
3. Call the Buildkite REST or GraphQL API with the token in the Authorization: Bearer header.
4. Cache the token in memory and refresh it before expiry. Do not exchange a new token for every request to prevent exhaustion of your token request rate-limits.

Setup

To use OAuth Token Exchange, you need:

1. A Token Exchange application configured on the Buildkite's side. Provide the following details for configuration:

• Name: A display name for the application.
• Description: A description of the application.
• JWKS: Your application's public key in JWKS format, provided as inline JSON or an https:// URI (see Provide your public key as a JWKS).
• Grantable scopes: The scopes that can be set on minted access tokens.
• Default scopes: The scopes set on minted access tokens when a token exchange request omits the scope parameter.
• Allowed IP addresses (optional, recommended): Restrict token usage to specific IP addresses.
• Maximum token TTL (optional): The maximum token lifetime in seconds. Defaults to 3600 (one hour).

After configuration, you will be provided with a client ID for your application.

Generate a key pair

Generate an RSA or ECDSA key pair. The private key stays with your application. The public key is registered with Buildkite as a JWKS.

RSA (2048-bit):

openssl genrsa -out private_key.pem 2048
openssl rsa -in private_key.pem -pubout -out public_key.pem

ECDSA (P-256):

openssl ecparam -name prime256v1 -genkey -noout -out private_key.pem
openssl ec -in private_key.pem -pubout -out public_key.pem

Provide your public key as a JWKS

Buildkite requires your public key in JWKS format — a JSON object containing a keys array with one or more JWK entries. You can provide it as inline JSON or as an https:// URI that serves the JWKS.

If your identity provider publishes a JWKS endpoint, use that directly. If you have a PEM-encoded public key, convert it to JWKS using a standards-compliant library in your language.

RSA key example:

{
  "keys": [
    {
      "kty": "RSA",
      "kid": "my-key-1",
      "use": "sig",
      "alg": "RS256",
      "n": "<base64url-encoded modulus>",
      "e": "AQAB"
    }
  ]
}

EC key example:

{
  "keys": [
    {
      "kty": "EC",
      "kid": "my-key-1",
      "use": "sig",
      "alg": "ES256",
      "crv": "P-256",
      "x": "<base64url-encoded x coordinate>",
      "y": "<base64url-encoded y coordinate>"
    }
  ]
}

All key component values (n, e, x, y) must be base64url-encoded.

Token exchange request

Exchange a signed JWT assertion for a Buildkite API token by sending a POST request to the token endpoint:

Endpoint: POST https://buildkite.com/oauth/token

POST /oauth/token HTTP/1.1
Host: buildkite.com
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:token-exchange
&client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
&client_assertion=eyJhbGciOi...
&subject_token=user@example.com
&subject_token_type=urn:buildkite:params:oauth:token-type:user-email
&audience=your-org-slug
&scope=read_pipelines read_builds

Request parameters

The subject user must be an active member of the target organization with a verified email address.

Response

A successful response returns a JSON object:

{
  "access_token": "bktx_...",
  "issued_token_type": "urn:ietf:params:oauth:token-type:access_token",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "read_pipelines read_builds"
}

Use the access_token value in the Authorization header for API requests:

Authorization: Bearer bktx_...

JWT assertion claims

The client_assertion is a JWT (RFC 7523) signed with your application's private key. It must contain these claims:

Optional claims:

Supported signing algorithms: RS256 (RSA) and ES256 (ECDSA P-256).

Example JWT header

{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "my-key-1"
}

Example JWT payload

{
  "iss": "0123456789abcdef0123",
  "sub": "0123456789abcdef0123",
  "aud": "https://buildkite.com/oauth/token",
  "iat": 1710849600,
  "exp": 1710849900,
  "jti": "550e8400-e29b-41d4-a716-446655440000"
}

Available scopes

Token exchange tokens support the same scopes as Buildkite API access tokens. The scopes granted to a token are limited to the application's configured grantable scopes.

Best practices

Follow these recommendations to keep your OAuth Token Exchange integration secure and reliable.

Cache and reuse tokens

Do not exchange a new token for every API request. This creates unnecessary load on the authentication infrastructure.

Instead, cache the token in memory and reuse it across requests. When the token is close to expiry, refresh it by performing another exchange.

Thread safety

If your application makes concurrent API calls, ensure your token cache is protected with a mutex or equivalent synchronization primitive.

Minimize scopes

Request only the scopes your application needs. Use the scope parameter to request a subset of the app's grantable scopes, rather than relying on the app's full default scopes.

Include a JTI claim

Include a unique jti (JWT ID) claim in each assertion to reduce replay risk. Use a UUID or another unique value for each request. After a successful token exchange, Buildkite rejects later requests that reuse the same jti.

Use short TTLs

Prefer shorter token lifetimes to limit the blast radius if a token is compromised. The expires_in parameter lets you request a TTL shorter than the app's maximum.

Example client

The buildkite-token-exchange-example repository contains a complete Go client that demonstrates the full token exchange flow, including JWT signing, token caching, and API calls.

Troubleshooting

The token endpoint returns RFC 6749 §5.2 error responses with an error code and optional error_description:

{
  "error": "invalid_client",
  "error_description": "Invalid client assertion signature"
}

Common errors