---
title: OIDC Federation Reference
product: vercel
url: /docs/oidc/reference
canonical_url: "https://vercel.com/docs/oidc/reference"
last_updated: 2026-09-17
type: reference
prerequisites:
  - /docs/oidc
related:
  - /docs/oidc/aws
summary: Review helper libraries to help you connect with your backend and understand the structure of an OIDC token.
install_vercel_plugin: npx plugins add vercel/vercel-plugin
search_with_vercel_cli: npx vercel@latest docs search "<query>"
---

# OIDC Federation Reference

> Secure backend access with OIDC federation is available on all plans

## Helper libraries

Vercel provides helper libraries to make it easier to exchange the OIDC token for short-lived credentials with your cloud provider.
They are available from the [@vercel/oidc](https://www.npmjs.com/package/@vercel/oidc) and [@vercel/oidc-aws-credentials-provider](https://www.npmjs.com/package/@vercel/oidc-aws-credentials-provider) packages on npm.


<!-- docsgraph:related -->
## Related pages

> **For AI agents:** Follow these links to understand how this page connects to the rest of the Vercel ecosystem. For the full cross-link map (inbound, outbound, prerequisites, and semantic neighbors), see the .graph.md link below.

- [Trusted Sources for Deployment Protection](https://vercel.com/changelog/trusted-sources-for-deployment-protection)
- [Death to long-lived static credentials](https://vercel.com/blog/death-to-long-lived-static-credentials)
- [Connect to your own API](https://vercel.com/docs/oidc/api) — Learn how to configure your own API to trust Vercel's OpenID Connect \\(OIDC\\) Identity Provider \\(IdP\\)
- [Connect to Microsoft Azure](https://vercel.com/docs/oidc/azure) — Learn how to configure your Microsoft Azure account to trust Vercel's OpenID Connect \\(OIDC\\) Identity Provider \\(IdP\\).
- [AI Gateway OIDC Authentication](https://vercel.com/docs/ai-gateway/authentication-and-byok/oidc) — Authenticate AI Gateway requests from Vercel deployments with OIDC tokens. Configure the AI SDK or send bearer tokens di
- [Authentication in Vercel Connect](https://vercel.com/docs/connect/concepts/authentication) — Every Vercel Connect token request has two legs that both have to authenticate: the caller calling Vercel Connect, and V
- [Create an issuer](https://vercel.com/docs/rest-api/kms/create-an-issuer) — POST /v1/kms/issuers — Create a new KMS issuer for the authenticated team, or for the team or organization identified by

Full cross-link map for this page: [/docs/oidc/reference.graph.md](/docs/oidc/reference.graph.md)
<!-- /docsgraph:related -->

### AWS SDK credentials provider

`awsCredentialsProvider()` is a helper function that returns a function that can be used as the `credentials` property of the
AWS SDK client. It exchanges the OIDC token for short-lived credentials with AWS by calling the `AssumeRoleWithWebIdentity`
operation.

You can pass an optional `audience` to exchange the default OIDC token for one with a custom `aud` claim. This is useful when your AWS trust policy expects a specific audience value. See [Custom audience](/docs/oidc/aws#custom-audience) for more details.

#### AWS S3 usage example

```ts
import { awsCredentialsProvider } from '@vercel/oidc-aws-credentials-provider';
import * as s3 from '@aws-sdk/client-s3';

const s3client = new s3.S3Client({
  region: process.env.AWS_REGION!,
  credentials: awsCredentialsProvider({
    roleArn: process.env.AWS_ROLE_ARN!,
    // optional custom audience
    audience: 'https://sts.amazonaws.com',
  }),
});
```

### Other cloud providers

In Node.js, `getVercelOidcToken()` from `@vercel/oidc` 4.0.0 and later checks the request context's `x-vercel-oidc-token` header first. If no header is present, it reads the file specified by `VERCEL_OIDC_TOKEN_FILE`, when set. Otherwise, it uses `VERCEL_OIDC_TOKEN`.

The SDK reads the configured file on every call and trims surrounding whitespace. Rotating the file updates the token on the next call without a process restart. An unreadable or empty configured file throws an error; it does not fall back to the environment variable. Don't cache the returned token.

The Edge Runtime entry point uses the request header or `VERCEL_OIDC_TOKEN`; it does not read `VERCEL_OIDC_TOKEN_FILE`.

You can pass an optional `audience` to exchange the default token for one with a custom `aud` claim:

#### Azure / CosmosDB example

```ts
import { getVercelOidcToken } from '@vercel/oidc';
import { ClientAssertionCredential } from '@azure/identity';
import { CosmosClient } from '@azure/cosmos';

const credentialsProvider = new ClientAssertionCredential(
  process.env.AZURE_TENANT_ID,
  process.env.AZURE_CLIENT_ID,
  () => getVercelOidcToken({
    // optional custom audience
    audience: 'api://AzureADTokenExchange',
  }),
);

const cosmosClient = new CosmosClient({
  endpoint: process.env.COSMOS_DB_ENDPOINT,
  aadCredentials: credentialsProvider,
});
```

> **💡 Note:** In the Vercel function environments, you cannot execute the
> `getVercelOidcToken()` function directly at the module level because the token
> is only available in the `Request` object as the `x-vercel-oidc-token` header.

## Team and project name changes

If you change the name of your team or project, the claims within the OIDC token will reflect the new names. This can affect
your trust and access control policies. You should consider this when you plan to rename your team or project and update your
policies accordingly.

AWS roles can support multiple conditions so you can allow access to both the old and new team and project names. The following example shows when the issuer mode is set to **global**:

```json filename="aws-trust-policy.json"
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Federated": "arn:aws:iam::[YOUR AWS ACCOUNT ID]:oidc-provider/oidc.vercel.com"
      },
      "Action": "sts:AssumeRoleWithWebIdentity",
      "Condition": {
        "StringEquals": {
          "oidc.vercel.com:aud": [
            "https://vercel.com/[OLD_TEAM_SLUG]",
            "https://vercel.com/[NEW_TEAM_SLUG]"
          ],
          "oidc.vercel.com:sub": [
            "owner:[OLD_TEAM_SLUG]:project:[OLD_PROJECT_NAME]:environment:production",
            "owner:[NEW_TEAM_SLUG]:project:[NEW_PROJECT_NAME]:environment:production"
          ]
        }
      }
    }
  ]
}
```

If your project is using the `team` issuer mode, you will need to create a new OIDC provider and add another statement to the trust policy:

```json filename="aws-trust-policy.json"
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "OldTeamName",
      "Effect": "Allow",
      "Principal": {
        "Federated": "arn:aws:iam::[YOUR AWS ACCOUNT ID]:oidc-provider/oidc.vercel.com/[OLD_TEAM_SLUG]"
      },
      "Action": "sts:AssumeRoleWithWebIdentity",
      "Condition": {
        "StringEquals": {
          "oidc.vercel.com/[OLD_TEAM_SLUG]:aud": [
            "https://vercel.com/[OLD_TEAM_SLUG]"
          ],
          "oidc.vercel.com/[OLD_TEAM_SLUG]:sub": [
            "owner:[OLD_TEAM_SLUG]:project:[OLD_PROJECT_NAME]:environment:production"
          ]
        }
      }
    },
    {
      "Sid": "NewTeamName",
      "Effect": "Allow",
      "Principal": {
        "Federated": "arn:aws:iam::[YOUR AWS ACCOUNT ID]:oidc-provider/oidc.vercel.com/[NEW_TEAM_SLUG]"
      },
      "Action": "sts:AssumeRoleWithWebIdentity",
      "Condition": {
        "StringEquals": {
          "oidc.vercel.com/[NEW_TEAM_SLUG]:aud": [
            "https://vercel.com/[NEW_TEAM_SLUG]"
          ],
          "oidc.vercel.com/[NEW_TEAM_SLUG]:sub": [
            "owner:[NEW_TEAM_SLUG]:project:[NEW_PROJECT_NAME]:environment:production"
          ]
        }
      }
    }
  ]
}
```

## OIDC token anatomy

You can validate OpenID Connect tokens by using the issuer's OpenID Connect Discovery Well Known location, which is either `https://oidc.vercel.com/.well-known/openid-configuration` or `https://oidc.vercel.com/[TEAM_SLUG]/.well-known/openid-configuration` depending on the issuer mode in your project settings. There, you can find a property called `jwks_uri` which
provides a URI to Vercel's public JSON Web Keys (JWKs). You can use the corresponding JWK identified by `kid` to verify tokens
that are signed with the same `kid` in the token's header.

### Example function token

```json
// Header:
{
  "typ": "JWT",
  "alg": "RS256",
  "kid": "example-key-id"
}
// Claims:
{
  "iss": "https://oidc.vercel.com/acme",
  "aud": "https://vercel.com/acme",
  "sub": "owner:acme:project:acme_website:environment:production",
  "iat": 1718885593,
  "nbf": 1718885593,
  "exp": 1718892793,
  "owner": "acme",
  "owner_id": "team_7Gw5ZMzpQA8h90F832KGp7nwbuh3",
  "project": "acme_website",
  "project_id": "prj_7Gw5ZMBpQA8h9GF832KGp7nwbuh3",
  "environment": "production"
}
```

### Standard OpenID Connect claims

This is a list of standard tokens that you can expect from an OpenID Connect JWT:

| Claim | Kind       | Description                                                                                                                                                                                |
| ----- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `iss` | Issuer     | When using the **team** issuer mode, the issuer is set to `https://oidc.vercel.com/[TEAM_SLUG]`<br />When using the **global** issuer mode, the issuer is set to `https://oidc.vercel.com`<br />When you pass a custom `audience`, the issuer is set to `https://oidc.vercel.com/[TEAM_SLUG]` in both issuer modes |
| `aud` | Audience   | Defaults to `https://vercel.com/[TEAM_SLUG]`. You can set a custom audience by passing the `audience` option to `getVercelOidcToken()` or `awsCredentialsProvider()` |
| `sub` | Subject    | The subject is set to `owner:[TEAM_SLUG]:project:[PROJECT_NAME]:environment:[ENVIRONMENT]`. `[ENVIRONMENT]` is `development`, `preview`, `production`, or a Custom Environment slug.       |
| `iat` | Issued at  | The time the token was created                                                                                                                                                             |
| `nbf` | Not before | The token is not valid before this time                                                                                                                                                    |
| `exp` | Expires at | Build tokens expire after one hour. Function tokens for `preview` and `production` expire after two hours. `development` tokens expire after 12 hours.                                     |

### Additional claims

These claims provide more granular access control:

| Claim                   | Description                                                                                                             |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `owner`                 | The team slug, e.g. `acme`                                                                                              |
| `owner_id`              | The team ID, e.g. `team_7Gw5ZMzpQA8h90F832KGp7nwbuh3`                                                                   |
| `project`               | The project name, e.g. `acme_website`                                                                                   |
| `project_id`            | The project ID, e.g. `prj_7Gw5ZMBpQA8h9GF832KGp7nwbuh3`                                                                 |
| `environment`           | The environment: `development`, `preview`, `production`, or a Custom Environment slug                                  |
| `custom_environment_id` | The stable Custom Environment ID. This claim is present only when the deployment targets a Custom Environment.          |
| `user_id`               | When environment is `development`, this is the ID of the user who was issued the token                                  |

### JWT headers

These headers are standard to the JWT tokens:

| Header | Kind      | Description                                      |
| ------ | --------- | ------------------------------------------------ |
| `alg`  | Algorithm | The algorithm used by the issuer                 |
| `kid`  | Key ID    | The identifier of the key used to sign the token |
| `typ`  | Type      | The type of token, this is set to `JWT`.         |

## Search the docs from your terminal

Search the Vercel docs and read pages as Markdown with the Vercel CLI. No login required.

```bash
# Find docs pages by keyword
npx vercel@latest docs search "environment variables"
npx vercel@latest docs search "function timeout"

# Print a docs page as Markdown, by path or URL
npx vercel@latest docs inspect <page>
```

---

[View full sitemap](/docs/sitemap)


If you encounter incorrect information, can’t find what you need, need a capability Vercel doesn’t currently offer, or have any other feedback to report, please do it by following the instructions at https://vercel.com/feedback.md.
