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 an external identity provider token for a Pulumi access token using the OAuth 2.0 Token Exchange flow (RFC 8693).

    The request body must include:

    • audience: a URN identifying the target org (e.g., urn:pulumi:org:{ORG_NAME})
    • grant_type: must be urn:ietf:params:oauth:grant-type:token-exchange
    • 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

    Optional parameters:

    • scope: 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: token lifetime in seconds

    The response includes 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.