# Workload Identity Federation

Authenticate to the Stripe API without a long-lived API key.

Workload Identity Federation (WIF) lets your service or application authenticate to the Stripe API without a long-lived API key. Instead, you set up a trust relationship between Stripe and your cloud provider’s identity service. When your service runs, it obtains a short-lived identity token from your cloud provider, exchanges it with Stripe for an access token scoped to your service principal, and uses that access token to call the Stripe API.

## Request access  (Private preview)

Workload Identity Federation is in [private preview](https://docs.stripe.com/release-phases.md) and available to a limited number of users.

### Get early access to Workload Identity Federation

Enter your email to request access to the Workload Identity Federation private preview.

```bash
curl https://docs.stripe.com/preview/register \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Referer: https://docs.stripe.com/workload-identity-federation" \
  -d '{"email": "EMAIL", "preview": "wif_private_preview"}'
```

## How WIF differs from API key authentication 

API keys in Stripe have no default expiration. Anyone who obtains your key can use it until you rotate or expire it, so a leaked key creates a potentially long-lived security risk.

With WIF, you never manually create or copy an API key to your cloud provider, and your service never holds a long-lived secret. After configuring a trusted identity provider and creating a service principal in Stripe, Stripe’s SDK automatically exchanges your cloud provider’s identity token for a short-lived Stripe access token that expires in 1 hour. If the exchanged token leaks, the exposure is limited to its remaining lifetime.

| Authentication method | Credential lifetime | What your workload stores | Requests allowed from |
| --- | --- | --- | --- |
| **API keys** | No expiration | A static secret | Anywhere (including curl requests) |
| **Workload Identity Federation** | 1 hour | No static secrets | Anywhere, but tokens can only be issued to a trusted workload |

## How it works 

1. **Your cloud provider issues an identity token.** Your workload runs as a cloud identity, such as a Google Cloud service account or an AWS IAM role. The Stripe SDK requests an identity token for Stripe from your cloud provider, which signs it.
2. **The SDK exchanges the identity token.** The SDK sends the identity token and your service principal’s client ID to Stripe. Stripe checks that the token’s issuer and subject match a [service principal](https://docs.stripe.com/service-principals.md) in your organization.
3. **Stripe issues an access token.** Stripe returns an access token that’s scoped to your service principal and expires in 1 hour. The SDK caches the access token and uses it for your Stripe API requests.
4. **The SDK refreshes the access token.** Before the access token expires, the SDK automatically repeats the exchange to get a new one. You don’t need to handle token expiration in your code.

A diagram of how a workload exchanges a cloud identity token for a short-lived Stripe access token (See full diagram at https://docs.stripe.com/workload-identity-federation)

```text
[Your workload (Stripe SDK)] -- Request identity token for Stripe --> [Cloud identity provider]
[Cloud identity provider] -- Return signed identity token --> [Your workload (Stripe SDK)]
[Your workload (Stripe SDK)] -- Send identity token and client ID oacli_... --> [Stripe token exchange]
[Stripe token exchange] -- Verify issuer and subject match the service principal --> [Stripe token exchange]
[Stripe token exchange] -- Return access token that expires in 1 hour --> [Your workload (Stripe SDK)]
[Your workload (Stripe SDK)] -- Make API requests with the access token --> [Stripe API]
[Stripe API] -- Return API responses --> [Your workload (Stripe SDK)]
[Your workload (Stripe SDK)] -- Before the access token expires, repeat the exchange --> [Your workload (Stripe SDK)]
```

To set up WIF, you create a cloud identity for your workload, create a service principal in Stripe that trusts that identity, and initialize the Stripe SDK with the service principal’s client ID.

## Set up Workload Identity Federation 

Follow the guide for your cloud provider. Each guide includes instructions for the cloud provider’s console, its CLI, and Terraform.

[Google Cloud](https://docs.stripe.com/workload-identity-federation/google-cloud.md): Learn how to authenticate to the Stripe API from Google Cloud with a service account and the Stripe Ruby SDK.

[AWS](https://docs.stripe.com/workload-identity-federation/aws.md): Learn how to authenticate to the Stripe API from AWS with an IAM role and the Stripe Node.js SDK.

## See also

- [Service principals](https://docs.stripe.com/service-principals.md)
- [Best practices for API keys](https://docs.stripe.com/keys-best-practices.md)