> ## 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.

# Workload Identity for HCP Terraform

> Let HCP Terraform or Terraform Enterprise runs call the Dodo Payments API with a workload identity token, with separate mappings for plan and apply.

HCP Terraform gives each plan and each apply phase a workload identity token. Dodo Payments trusts this token through a `terraform_cloud` provider.

## Provider Settings

| Setting | Value |
| - | - |
| Provider type | `terraform_cloud` |
| Issuer | `https://app.terraform.io`, or the URL of your Terraform Enterprise |
| Audience | `https://live.dodopayments.com` or `https://test.dodopayments.com` |
| Replay protection | Each JWT can do one exchange (`jti`). |
| JWT lifetime | 24 hours or less. |
| Dodo token lifetime | Until the JWT expires (the end of the run phase), 24 hours maximum. |

## Required Claims

The mapping must pin both `terraform_organization_id` and `terraform_workspace_id`. Pin `terraform_run_phase` to split plan and apply:

```json theme={null}
[
  { "claim": "terraform_organization_id", "value": "org-..." },
  { "claim": "terraform_workspace_id", "value": "ws-..." },
  { "claim": "terraform_run_phase", "value": "apply" }
]
```

Create a second mapping with `terraform_run_phase` set to `plan` and read scopes only.

## Workspace Configuration

In the 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_...` |

HCP Terraform then sets `TFC_WORKLOAD_IDENTITY_TOKEN` in each run phase.

## Terraform Provider

```hcl theme={null}
provider "dodopayments" {
  environment = "live_mode"
  workload_identity {
    token_source = "terraform_cloud"
  }
}
```

The provider does one exchange at the start of each phase. Refer to [Terraform](https://docs.dodopayments.com/developer-resources/workload-identity/terraform.md).

## SDK Usage

For code that runs in a Terraform run, for example an external data source, use the `terraformCloud()` helper:

```typescript TypeScript theme={null}
import DodoPayments from 'dodopayments';

const client = new DodoPayments({
  environment: 'live_mode',
  workloadIdentity: {
    identityProviderId: process.env.DODO_PAYMENTS_IDENTITY_PROVIDER_ID,
    provider: DodoPayments.workloadIdentity.terraformCloud(),
  },
});
```

```python Python theme={null}
import os
from dodopayments import DodoPayments
from dodopayments.workload_identity import WorkloadIdentity, terraform_cloud

client = DodoPayments(
    environment="live_mode",
    workload_identity=WorkloadIdentity(
        identity_provider_id=os.environ["DODO_PAYMENTS_IDENTITY_PROVIDER_ID"],
        provider=terraform_cloud(),
    ),
)
```

```go Go theme={null}
client := dodopayments.NewClient(
	option.WithEnvironmentLiveMode(),
	option.WithWorkloadIdentity(option.WorkloadIdentity{
		IdentityProviderID: os.Getenv("DODO_PAYMENTS_IDENTITY_PROVIDER_ID"),
		Provider:           workloadidentity.TerraformCloud(),
	}),
)
```

> [!WARNING]
>
> The JWT of a phase can do one exchange only. Two processes that read the same `TFC_WORKLOAD_IDENTITY_TOKEN` cannot both do an exchange. The second exchange fails with the `replay` reason.


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