Skip to main content
This guide shows you how to create a Buildkite Token Exchange App. Nango signs a JWT with your app’s private key and exchanges it for short-lived API tokens. You need:
  • A Buildkite Enterprise plan. Token exchange isn’t available on other plans.
  • Organization administrator permissions in Buildkite.
1

Generate a signing key

Create a private key and a JWKS containing its public key. Buildkite supports RSA keys (RS256) and EC P-256 keys (ES256).
The second command prints your JWKS. Buildkite requires a kid on every key. Here it’s nango-1, and that’s your Key ID. Keep private.pem secret.
2

Create a Token Exchange App

  1. In Buildkite, go to Organization Settings > Integrations > Token Exchange Apps.
  2. Click Create a Token Exchange App.
  3. Fill in:
    • Name and Description
    • JWKS — paste the JSON from the previous step, or an https:// URL that serves it.
    • Grantable Scopes — the scopes tokens from this app can have, such as read_pipelines and read_builds.
    • Default Scopes — required for Nango. Nango doesn’t send a scope parameter, so every token gets these scopes. If you leave them empty, token requests fail.
    • Allowed IPs for Token Exchange Requests and Allowed IPs for Minted Token Usage (optional) — Nango both requests the tokens and calls the API with them. If you restrict either, include all of Nango’s IP addresses.
    • Max Token TTL (seconds) — up to 86,400 (24 hours). Tokens last one hour by default, capped at this value.
  4. Save the app.
3

Copy your Client ID

Copy the Client ID from the app’s page.
4

Add your app to Nango

In your Buildkite (Token Exchange) integration in Nango, enter:
  • Client ID — from the previous step.
  • Key ID — the kid from your JWKS.
  • Private Key — the full contents of private.pem, including the BEGIN and END lines.
  • Signing Algorithm — RS256 for an RSA key, ES256 for an EC key.
For more details, see Buildkite’s OAuth token exchange documentation.