> ## 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 Kubernetes and Amazon EKS

> Call the Dodo Payments API from a Kubernetes pod with a projected service account token, on any cluster with a public OIDC issuer, including Amazon EKS.

A Kubernetes pod can get a service account token with a custom audience as a projected volume. Dodo Payments trusts this token through a `kubernetes` provider. Use this type for Amazon EKS also. Do not use the `aws` type for EKS.

## Provider Settings

| Setting | Value |
| - | - |
| Provider type | `kubernetes` |
| Issuer | The issuer of your cluster, for example `https://oidc.eks.<region>.amazonaws.com/id/<id>` on EKS |
| Audience | Must be `https://live.dodopayments.com` or `https://test.dodopayments.com` |
| Replay protection | Not enforced. All processes in the pod read the same token until the kubelet writes a new one. |
| JWT lifetime | 24 hours or less. |

Dodo Payments must be able to get the discovery document and the JWKS of the issuer over HTTPS. The EKS OIDC issuer is public. For a cluster with a private issuer, use a `custom` provider with uploaded keys. Refer to [Custom OIDC](https://docs.dodopayments.com/developer-resources/workload-identity/providers/custom-oidc.md).

To find the issuer of an EKS cluster, run:

```bash theme={null}
aws eks describe-cluster --name my-cluster \
  --query "cluster.identity.oidc.issuer" --output text
```

## Required Claims

The mapping must pin `sub` to one service account:

```json theme={null}
[
  { "claim": "sub", "value": "system:serviceaccount:payments:billing-worker" }
]
```

Conditions read top-level claims only. The namespace and the pod are in the `kubernetes.io` object, thus pin them through `sub`.

> [!TIP]
>
> Add the egress IPs of the cluster, for example the NAT gateway IPs, to the `allowed_cidrs` of the mapping. A stolen token file then cannot do an exchange from another network.

## Pod Configuration

Mount a projected service account token with the Dodo Payments audience, and point `DODO_PAYMENTS_IDENTITY_TOKEN_FILE` to it:

```yaml expandable theme={null}
apiVersion: v1
kind: ServiceAccount
metadata:
  name: billing-worker
  namespace: payments
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: billing-worker
  namespace: payments
spec:
  replicas: 2
  selector:
    matchLabels:
      app: billing-worker
  template:
    metadata:
      labels:
        app: billing-worker
    spec:
      serviceAccountName: billing-worker
      containers:
        - name: worker
          image: ghcr.io/acme/billing-worker:latest
          env:
            - name: DODO_PAYMENTS_IDENTITY_PROVIDER_ID
              value: wip_...
          volumeMounts:
            - name: dodo-token
              mountPath: /var/run/secrets/tokens
              readOnly: true
      volumes:
        - name: dodo-token
          projected:
            sources:
              - serviceAccountToken:
                  path: dodo-token
                  audience: https://live.dodopayments.com
                  expirationSeconds: 3600
```

The kubelet writes a new token when the token is older than 80% of its life. With `expirationSeconds: 3600`, this occurs after about 48 minutes. The SDK reads the file again for each exchange.

## SDK Usage

```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.kubernetes(),
  },
});
```

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

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

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

The `kubernetes()` helper reads `/var/run/secrets/tokens/dodo-token`. To use a different path, give the path to the helper.

Refer to [SDK Usage](https://docs.dodopayments.com/developer-resources/workload-identity/sdk-usage.md) for the other languages.


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