> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dodopayments.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Use Workload Identity with the Terraform Provider

> Configure the Dodo Payments Terraform provider with a workload_identity block, so that plan and apply runs need no stored API key.

The [Dodo Payments Terraform provider](https://docs.dodopayments.com/developer-resources/terraform-provider.md) 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.

> [!NOTE]
>
> The `workload_identity` block is available from provider version 0.3.0.

## Provider Configuration

```hcl theme={null}
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-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. |

> [!WARNING]
>
> 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

**1. 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](https://docs.dodopayments.com/developer-resources/workload-identity/providers/terraform-cloud.md).

**2. 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_...` |

**3. 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.

```yaml expandable theme={null}
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
```

```hcl theme={null}
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](https://docs.dodopayments.com/developer-resources/terraform-provider.md)**
>
> Manage your catalog as code.

> **[Terraform Cloud Guide](https://docs.dodopayments.com/developer-resources/workload-identity/providers/terraform-cloud.md)**
>
> Provider and mapping setup for HCP Terraform.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.