Use Workload Identity with the Terraform Provider

The Dodo Payments Terraform provider accepts a workload_identity block in place of api_key. The provider gets a JWT from the platform that runs Terraform, exchanges it, and uses the Dodo token for the run.

The workload_identity block is available from provider version 0.3.0.

Provider Configuration

provider "dodopayments" {
  environment = "live_mode"

  workload_identity {
    identity_provider_id = "wip_..."
    token_source         = "terraform_cloud"
  }
}

workload_identity is a block, not an attribute. Do not write workload_identity = { ... }.

Attribute	Description
`identity_provider_id`	The identity provider id. If you do not set it, the provider reads `DODO_PAYMENTS_IDENTITY_PROVIDER_ID`.
`token_source`	Where the provider gets the JWT. The default value is `auto`. Refer to Token Sources.
`token_file`	The path of the JWT file. Use it with `token_source = "file"`.
`audience`	The audience of the JWT for the `github_actions` and `gcp` token sources. The default value is the origin of the API base URL.

Do not set api_key and workload_identity together. The provider gives an error when you set the two. If you set neither, the provider reads DODO_PAYMENTS_API_KEY. If DODO_PAYMENTS_API_KEY is not set and DODO_PAYMENTS_IDENTITY_PROVIDER_ID is set, the provider uses workload identity with the auto token source.

Token Sources

`token_source`	How the provider gets the JWT
`auto`	Finds the platform from the environment. This is the default value.
`github_actions`	Requests a token from the GitHub OIDC endpoint (`ACTIONS_ID_TOKEN_REQUEST_URL`). A long apply can get a new token.
`gitlab`	Reads the ID token of the GitLab job.
`terraform_cloud`	Reads `TFC_WORKLOAD_IDENTITY_TOKEN`. The provider does one exchange at the start of the plan or apply phase.
`gcp`	Requests an identity token from the Google Cloud metadata server.
`vercel`	Reads the Vercel OIDC token.
`kubernetes`	Reads the projected service account token.
`file`	Reads the file in `token_file`.

HCP Terraform

Create the provider and the mappings

In the dashboard, create a terraform_cloud provider. Then add mappings that pin terraform_organization_id and terraform_workspace_id. Refer to Terraform Cloud.

Set the workspace variables

In the HCP Terraform workspace, add these environment variables:

Variable	Value
`TFC_WORKLOAD_IDENTITY_AUDIENCE`	`https://live.dodopayments.com` (or `https://test.dodopayments.com`)
`DODO_PAYMENTS_IDENTITY_PROVIDER_ID`	`wip_...`

Configure the provider

Set token_source = "terraform_cloud" in the workload_identity block. Remove DODO_PAYMENTS_API_KEY from the workspace.

Split Plan and Apply

HCP Terraform adds the terraform_run_phase claim (plan or apply) to the JWT. Use it to give the plan phase read access only:

Mapping	Conditions	Scopes
Plan	`terraform_organization_id`, `terraform_workspace_id`, `terraform_run_phase = plan`	Read scopes
Apply	`terraform_organization_id`, `terraform_workspace_id`, `terraform_run_phase = apply`	Read and write scopes

Each JWT matches one mapping only, because the two mappings have different terraform_run_phase values. A terraform_cloud Dodo token lives until the end of the run phase, with a maximum of 24 hours. Pin terraform_run_phase to keep write access in the apply phase only.

GitHub Actions

Give the job the id-token: write permission. The provider requests the JWT. If you do not add a workload_identity block and DODO_PAYMENTS_API_KEY is not set, the auto token source finds GitHub Actions.

jobs:
  apply:
    runs-on: ubuntu-latest
    permissions:
      id-token: write
      contents: read
    env:
      DODO_PAYMENTS_IDENTITY_PROVIDER_ID: wip_...
    steps:
      - uses: actions/checkout@v4
      - uses: hashicorp/setup-terraform@v3
      - run: terraform init
      - run: terraform apply -auto-approve

provider "dodopayments" {
  environment = "live_mode"
  workload_identity {
    token_source = "github_actions"
  }
}

Environment Variables

Variable	Use
`DODO_PAYMENTS_IDENTITY_PROVIDER_ID`	The identity provider id, when the block does not set `identity_provider_id`.
`TFC_WORKLOAD_IDENTITY_AUDIENCE`	HCP Terraform workspace variable. Set it to the Dodo Payments audience.
`TFC_WORKLOAD_IDENTITY_TOKEN`	Set by HCP Terraform. The `terraform_cloud` source reads it.

Terraform Provider

Manage your catalog as code.

Terraform Cloud Guide

Provider and mapping setup for HCP Terraform.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Use Workload Identity with the Terraform Provider

Provider Configuration

Token Sources

HCP Terraform

Split Plan and Apply

GitHub Actions

Environment Variables

Terraform Provider

Terraform Cloud Guide

​Provider Configuration

​Token Sources

​HCP Terraform

​Split Plan and Apply

​GitHub Actions

​Environment Variables

Terraform Provider

Terraform Cloud Guide

Provider Configuration

Token Sources

HCP Terraform

Split Plan and Apply

GitHub Actions

Environment Variables