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

# Set Up Workload Identity in the Dashboard

> Create an identity provider and a mapping in the Dodo Payments dashboard, then view and revoke workload tokens and examine the audit events.

You manage workload identity only in the dashboard. There is no public API to create providers or mappings. Each provider belongs to the mode that you select in the dashboard, test mode or live mode. To use both modes, create one provider in each mode.

To open the page, go to **Developer → Workload Identity** in the dashboard.

![Workload Identity page in the dashboard that lists the identity providers of the business](https://mintcdn.com/dodopayments/rF0hPasO2gd-TLgx/images/workload-identity/providers-list.png?fit=max\&auto=format\&n=rF0hPasO2gd-TLgx\&q=85\&s=ee134382abe83b9cb60ae2e448e75b87)

## Permissions

| Action | Scope that the dashboard user must hold |
| - | - |
| View providers, mappings, tokens, and events | `api_keys:read` |
| Create, change, or delete a provider or a mapping | `api_keys:write` |
| Revoke one token or all tokens of a mapping | `api_keys:write` |

A mapping issues tokens like an API key. Thus each scope of a mapping must be a scope that you hold. You cannot change a mapping that has a scope that you do not hold.

## Create a Provider

**1. Open Workload Identity**

In the dashboard, go to **Developer → Workload Identity**. Make sure that the mode switch shows the mode that you want.

**2. Select the provider type**

Click **Add Provider** and select the platform of your workload.

![Provider type picker with logos for GitHub Actions, GitLab, Terraform Cloud, Google Cloud, Vercel, Kubernetes, AWS, and Custom OIDC](https://mintcdn.com/dodopayments/rF0hPasO2gd-TLgx/images/workload-identity/create-provider.png?fit=max\&auto=format\&n=rF0hPasO2gd-TLgx\&q=85\&s=8d077eb5b237b13f8780117fa906ded0)

**3. Enter the issuer and the audience**

Enter a name for the provider. The issuer and the audience have default values for most types:

| Provider type | Issuer |
| - | - |
| `github_actions` | `https://token.actions.githubusercontent.com` (fixed) |
| `gitlab` | `https://gitlab.com`, or the URL of your self-managed GitLab |
| `terraform_cloud` | `https://app.terraform.io`, or the URL of your Terraform Enterprise |
| `gcp` | `https://accounts.google.com` (fixed) |
| `vercel` | `https://oidc.vercel.com/<team_slug>` |
| `aws` | `https://<id>.tokens.sts.global.api.aws` |
| `kubernetes` | The issuer of your cluster |
| `custom` | Any HTTPS URL |

The default audience is `https://live.dodopayments.com` in live mode and `https://test.dodopayments.com` in test mode. Keep the default unless your platform cannot use it.

**4. Save the provider**

Click **Create**. Dodo Payments gets the discovery document and the JWKS of the issuer before it saves the provider. If the keys are not available, the dashboard shows an error that names the field.

A `custom` provider can have a `discovery_url`, or uploaded public keys (JWKS) for an issuer that does not publish its keys.

**5. Copy the provider id**

Open the provider and copy its id (`wip_...`). Your workload uses this id. It is not a secret.

![Provider detail page with the provider id, the issuer, the audience, and the list of mappings](https://mintcdn.com/dodopayments/rF0hPasO2gd-TLgx/images/workload-identity/provider-detail.png?fit=max\&auto=format\&n=rF0hPasO2gd-TLgx\&q=85\&s=9b0ec766dd50d419f486965ac6c78031)

> [!WARNING]
>
> A change to the audience, the discovery URL, or the uploaded keys of a provider revokes all tokens of all its mappings. A deleted provider also deletes its mappings and revokes their tokens.

## Add a Mapping

A mapping tells Dodo Payments which JWTs to trust and which scopes to give them.

![Create mapping form with claim conditions, API scopes, allowed CIDR ranges, and token lifetime](https://mintcdn.com/dodopayments/rF0hPasO2gd-TLgx/images/workload-identity/create-mapping.png?fit=max\&auto=format\&n=rF0hPasO2gd-TLgx\&q=85\&s=5a87e9e64dfd23851e951a4eb266f2bb)

**1. Open the provider**

On the provider detail page, click **Add Mapping**.

**2. Add the conditions**

Each condition has a claim name and a value. All conditions must match (AND). A claim that is not in the JWT never matches.

```json theme={null}
[
  { "claim": "repository_owner_id", "value": "123456" },
  { "claim": "repository_id", "value": "987654321" },
  { "claim": "ref", "value": "refs/heads/main" }
]
```

* Add 1 to 20 conditions. A claim name has 128 characters or fewer. A value has 512 characters or fewer.
* A value can end with one `*` after a prefix, for example `repo:acme/billing:*`. A value of only `*`, or a `*` in the middle, is not permitted.
* Dodo Payments compares a number or a boolean claim in its JSON text form. Thus `"123456"` matches the number `123456`.
* Conditions read top-level claims only.
* Each provider type has required claims that you must pin with an exact value. Refer to the guide for your platform.

**3. Select the scopes**

Select the API scopes that the workload needs. Give the smallest set of scopes.

**4. Add allowed CIDR ranges (optional)**

Enter the IPv4 or IPv6 ranges of your workload, for example `203.0.113.0/24`. The exchange and each API call must come from an IP in the list.

**5. Set the token lifetime (optional)**

Enter a value between 300 and 3600 seconds. The default is 3600 seconds. The `terraform_cloud` type ignores this value and uses the end of the run phase.

**6. Save the mapping**

Click **Create**. The mapping is active immediately.

> [!TIP]
>
> Make sure that a JWT matches exactly one mapping. If two enabled mappings match, the exchange fails with the `multiple_mappings` reason.

A change to a mapping or a deleted mapping revokes all tokens of that mapping.

## View and Revoke Tokens

Open a mapping to see its active tokens. The list shows the token prefix, the creation time, the expiry time, and the last use.

![Active tokens of a mapping with the prefix, created time, expiry time, and last used time](https://mintcdn.com/dodopayments/rF0hPasO2gd-TLgx/images/workload-identity/tokens-list.png?fit=max\&auto=format\&n=rF0hPasO2gd-TLgx\&q=85\&s=bd871a8e12821b46bd6ce96fb87271ba)

* To revoke one token, click **Revoke** on the row of the token.
* To revoke all tokens of the mapping, click **Revoke All Tokens**. The mapping stays, and the workload can do a new exchange.

![Confirmation dialog to revoke all active tokens of a mapping](https://mintcdn.com/dodopayments/rF0hPasO2gd-TLgx/images/workload-identity/revoke-tokens.png?fit=max\&auto=format\&n=rF0hPasO2gd-TLgx\&q=85\&s=4066903f7203bf1c145ab6f7cc9b2226)

Workload tokens do not show on the **Developer → API Keys** page, and you cannot change them there.

To stop a workload permanently, disable or delete its mapping. Revoking a token does not stop the next exchange.

## View Events

The events list shows each exchange, failure, revocation, and configuration change for 90 days. Filter the list by provider, mapping, event type, or time range.

![Workload identity events list with event types, reason codes such as Too many failed exchanges in one minute, and source IPs](https://mintcdn.com/dodopayments/rF0hPasO2gd-TLgx/images/workload-identity/events-list.png?fit=max\&auto=format\&n=rF0hPasO2gd-TLgx\&q=85\&s=ca3de2d868ea72765f549665a15e5ebb)

For a failed exchange, the reason code tells you what to correct. For example, `no_mapping` means that no mapping condition matched, and `audience_mismatch` means that the workload requested the JWT with the wrong audience. Refer to [Reason Codes](https://docs.dodopayments.com/developer-resources/workload-identity/overview.md#reason-codes) for the full list.

> **[SDK Usage](https://docs.dodopayments.com/developer-resources/workload-identity/sdk-usage.md)**
>
> Configure your workload to use the provider.

> **[Overview](https://docs.dodopayments.com/developer-resources/workload-identity/overview.md)**
>
> Token lifetime, revocation, and audit rules.


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