Skip to main content
Sign in Dashboard Get started
  1. Docs
  2. Reference
  3. REST API Docs
  4. OAuth Token Exchange

OAuth Token Exchange

    The OAuth Token Exchange API allows you to exchange external identity tokens (like those from OIDC providers) for Pulumi access tokens. This enables automated workflows to authenticate with Pulumi Cloud without storing long-lived credentials.

    Token

    ▼
    POST /api/oauth/token

    Exchanges a presented credential for a Pulumi access token. Two grant types are supported, selected by the grant_type field in the request body.

    Token exchange (RFC 8693). Exchanges an external OIDC identity provider token for a Pulumi access token. Request body:

    • grant_type: must be urn:ietf:params:oauth:grant-type:token-exchange
    • audience: a URN identifying the target org (e.g., urn:pulumi:org:{ORG_NAME})
    • subject_token: the OIDC identity token from the external provider
    • subject_token_type: must be urn:ietf:params:oauth:token-type:id_token
    • requested_token_type: one of urn:pulumi:token-type:access_token:organization, ...team, ...personal, or ...runner
    • scope (optional): depends on the requested token type. For organization, must be empty or admin. For team, must be team:TEAM_NAME. For personal, must be user:USER_LOGIN. For runner, must be runner:RUNNER_NAME.
    • expiration (optional): token lifetime in seconds.

    Refresh token (RFC 6749 §6). Exchanges a Pulumi-issued refresh token for a short-lived on-behalf-of access token bound to the user the refresh token resolves to. Request body:

    • grant_type: must be refresh_token
    • refresh_token: the refresh-token value previously issued by Pulumi.

    Both grants return the same response shape: access_token, issued_token_type, token_type, expires_in, scope, and refresh_token.

    Request Body

    Responses

    200 OK
    Schema: TokenExchangeGrantResponse
    • access_token string required
      The security token issued by the authorization server.
    • issued_token_type string required
      The type of the issued token.
    • token_type string required
      The token type (e.g., Bearer).
    • expires_in integer required
      The lifetime in seconds of the access token.
    • scope string required
      The scope of the access token.
    • refresh_token string optional
      The refresh token, if issued.