Docs Home Pulumi IaC Pulumi ESC Pulumi Insights Pulumi IDP Pulumi Cloud Packages Tutorials
  1. Docs
  2. Pulumi Cloud
  3. Pulumi Cloud REST API
  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 Exchange Operations

    The API provides an endpoint for exchanging tokens:

    • Exchanging external tokens for Pulumi access tokens of various types

    Exchange Token

    Exchange an external token for a Pulumi token via an OIDC issuer trust relationship.

    POST /api/oauth/token

    Parameters

    ParameterTypeInDescription
    audiencestringbodyOAuth audience in the form urn:pulumi:org:ORG_NAME
    grant_typestringbodyOAuth grant type (only urn:ietf:params:oauth:grant-type:token-exchange is supported)
    subject_token_typestringbodyOAuth subject token type (only urn:ietf:params:oauth:token-type:id_token is supported)
    requested_token_typestringbodyOAuth requested token type (prefix of urn:pulumi:token-type:access_token:TOKEN_TYPE where TOKEN_TYPE is organization, team, personal, or runner)
    expirationnumberbodyOAuth token expiration in seconds
    scopestringbodyOAuth scope as a comma-separated array. This depends on the requested token type. For requested token type organization, scopes must be empty or admin. For team, the scope must be team:TEAM_NAME. For personal, it must be user:USER_LOGIN. For runner, it must be runner:RUNNER_NAME.
    subject_tokenstringbodyThe external token to exchange (usually from your OIDC provider)

    Example

    curl \
  -H "Accept: application/vnd.pulumi+8" \
  -H "Content-Type: application/json" \
  --request POST \
  --data '{"audience":"urn:pulumi:org:ORG_NAME","grant_type":"urn:ietf:params:oauth:grant-type:token-exchange","subject_token_type":"urn:ietf:params:oauth:token-type:id_token","requested_token_type":"urn:pulumi:token-type:access_token:organization","expiration":7200,"scope":"","subject_token":"$SOURCE_TOKEN"}' \
  https://api.pulumi.com/api/oauth/token

    Default response

    Status: 200 OK

    {
  "access_token": "redacted",
  "issued_token_type": "urn:pulumi:token-type:access_token:organization",
  "token_type": "token",
  "expires_in": 7200,
  "scope": "",
  "refresh_token": ""
}