---
title: "Create an HCP Terraform persona mapping"
method: POST
path: "/api/v2/wif/terraform/persona_mapping"
tags: ["Cloud Authentication"]
---

# Create an HCP Terraform persona mapping

`POST /api/v2/wif/terraform/persona_mapping`

## Request

- Base URL: `https://api.datadoghq.com`
- URL: `https://api.datadoghq.com/api/v2/wif/terraform/persona_mapping`
- Auth: one of:
  - API key in header `DD-API-KEY` and API key in header `DD-APPLICATION-KEY`
  - OAuth 2
    - Authorization code: `/oauth2/v1/authorize`
    - Token URL: `/oauth2/v1/token` scopes: `workload_identity_federation_write`

Create an HCP Terraform persona mapping. The mapping associates a Datadog user or service account with workload identity tokens from an HCP Terraform issuer whose `sub` claim matches `sub_pattern`.

The response includes the `audience` value to set as the `TFC_WORKLOAD_IDENTITY_AUDIENCE_DATADOG` environment variable in HCP Terraform. The API returns a 409 error if the pattern duplicates an existing mapping, or if it can match the same token as an existing mapping for a different account.

## Request body

- TerraformCloudAuthPersonaMappingCreateRequest: Request to create an HCP Terraform persona mapping.
  - `data` TerraformCloudAuthPersonaMappingCreateData, required: Data for creating an HCP Terraform persona mapping.
    - `attributes` TerraformCloudAuthPersonaMappingCreateAttributes, required: Attributes for creating an HCP Terraform persona mapping.
      - `account_identifier` string, required: Handle or email address of the Datadog user or service account that matching tokens authenticate as. Its permissions must not exceed the caller's.
      - `issuer_url` 'https://app.terraform.io' | 'https://app.eu.terraform.io', required: HCP Terraform workload identity token issuer. Use `https://app.terraform.io` for HCP Terraform in the US or `https://app.eu.terraform.io` for HCP Terraform in Europe.
      - `sub_pattern` string, required: Pattern matched against the `sub` claim of HCP Terraform workload identity tokens. Use `organization:<org>:project:<project>:workspace:<workspace>:run_phase:<plan|apply>` for workspace runs, or `organization:<org>:module:<module>:operation:test_run` for module test runs. Segments are HCP Terraform names, not IDs. Any segment except the organization can be `*` to match any value.
    - `type` 'terraform_cloud_auth_config', required: Type identifier for an HCP Terraform persona mapping.

## Response `201`

Created

- TerraformCloudAuthPersonaMappingResponse: Response containing a single HCP Terraform persona mapping.
  - `data` TerraformCloudAuthPersonaMappingDataResponse, required: HCP Terraform persona mapping resource.
    - `attributes` TerraformCloudAuthPersonaMappingAttributesResponse, required: Stored HCP Terraform persona mapping attributes.
      - `account_identifier` string, required: Handle of the mapped Datadog account, resolved when the mapping was created.
      - `account_uuid` string, required: UUID of the mapped Datadog user or service account.
      - `audience` string: Audience to set as the `TFC_WORKLOAD_IDENTITY_AUDIENCE_DATADOG` environment variable in HCP Terraform. Datadog computes this value as `datadog/<organization UUID>`.
      - `issuer_url` string: HCP Terraform workload identity token issuer. Empty for mappings created before the issuer was required.
      - `sub_pattern` string, required: Pattern matched against the `sub` claim of HCP Terraform workload identity tokens.
    - `id` string, required: Unique identifier of the persona mapping.
    - `type` 'terraform_cloud_auth_config', required: Type identifier for an HCP Terraform persona mapping.

## Other responses

- `400`: Bad Request
- `403`: Forbidden
- `409`: Conflict
- `429`: Too many requests

## Changes

- **2026-11-20** `3b1c63e31740`: 4 warning
  - the optional response header `X-RateLimit-Limit` removed for the status `429`
  - the optional response header `X-RateLimit-Period` removed for the status `429`
  - the optional response header `X-RateLimit-Remaining` removed for the status `429`
  - the optional response header `X-RateLimit-Reset` removed for the status `429`
- **2026-11-19** `e80219fa3b5c`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/datadog/apis/datadog-api-v2-collection/changes/api/v2/wif/terraform/persona_mapping/post.md)

---

[API](https://skmtc.dev/datadog/apis/datadog-api-v2-collection.md) - [All operations](https://skmtc.dev/datadog/apis/datadog-api-v2-collection/llms.txt) - [OpenAPI document](https://skmtc.dev/datadog/apis/datadog-api-v2-collection/revisions/4ba32926196d?raw)
