---
title: How do I use a Vercel API Access Token?
description: Create a Vercel API access token, scope it to your account, a team, or a project, and use it to authenticate Vercel REST API and CLI requests.
url: "https://vercel.com/kb/guide/how-do-i-use-a-vercel-api-access-token"
published: 2025-11-03
last_updated: 2026-10-01
authors: Vercel
install_vercel_plugin: npx plugins add vercel/vercel-plugin
---

Vercel access tokens authenticate your requests to the Vercel REST API and the Vercel CLI, which lets scripts, CI jobs, and integrations act on your behalf. Each token carries a scope that limits it to your full account, a single team, or a single project. Choosing the narrowest scope that covers the work keeps a leaked token from reaching anything outside that scope.

In this guide, you'll learn how to:

- Choose the right scope for an access token
  
- Create a token in the dashboard and store it securely
  
- Authenticate a REST API request with the token
  
- Target a team's resources from a full-account token
  
- Fix common authentication errors
  

## Prerequisites

- A Vercel account
  
- Membership in the team that owns the project, if you're creating a team- or project-scoped token
  
- Two-factor authentication enabled on your account, if the team requires it
  
- A terminal with `curl`, and an active Node.js LTS release for the JavaScript examples
  

## How token scopes limit access

Every token has a scope that sets which accounts, teams, and projects it can read and write. Vercel supports three scope levels:

| Scope        | What the token can access                                                                                                     | Needs `teamId` for team resources |
| ------------ | ----------------------------------------------------------------------------------------------------------------------------- | --------------------------------- |
| Full Account | Your personal account and every team you belong to                                                                            | Yes                               |
| Team         | All projects and resources in one team                                                                                        | No                                |
| Project      | Resources in one project within a team. Requests to other projects, team-level resources, or user-level resources are denied. | No                                |

Pick the narrowest scope that covers the work. If a deploy script only touches one project, give it a project-scoped token so a leak can't reach your other projects or your team's settings.

Some teams require two-factor authentication or SAML before you can create a token scoped to them. When you select a team that enforces this, the dashboard tells you.

## How to create a Vercel access token

Tokens belong to your user account, so you create them from your account settings rather than a team's settings, even when you scope a token to a team or project:

1. Open the [Account Tokens page](https://vercel.com/account/tokens) in your account settings.
   
2. Enter a descriptive token name, such as `ci-deploy-prod`, so you can tell later which script or integration uses it.
   
3. Open the **Scope** dropdown. Select **Full Account** for access to everything, or select a team to open its project list. From there, select **All Projects** to create a team-scoped token, or select one project to create a project-scoped token.
   
4. Choose an expiration and select **Create**. Once the expiration date passes, the token stops working even if you forget to revoke it.
   
5. Copy the token before you leave the page. Personal access tokens begin with `vcp_`, and Vercel shows the value only once.
   

Store the token in a secret manager or an environment variable, and never commit it to source control. If you lose a token, create a replacement and delete the lost one from the Account Tokens page.

## How to authenticate an API request with your access token

Every request to the Vercel REST API passes the token as a Bearer token in the `Authorization` header. To keep the token out of your shell history, read it into the `VERCEL_TOKEN` environment variable instead of typing it into a command. Run the following, paste the token when the terminal waits for input, and press Enter:

```bash
read -s VERCEL_TOKEN && export VERCEL_TOKEN
```

The shell doesn't display the token as you paste it. In the same terminal, list the projects your token can reach with `GET /v10/projects`:

```bash
curl "https://api.vercel.com/v10/projects?limit=1" \
  -H "Authorization: Bearer $VERCEL_TOKEN"
```

When the request succeeds, the API returns HTTP 200 and a JSON body listing the projects in the token's scope. The `limit=1` parameter caps the response at one project.

In a server-side Node.js script, read the token from the same environment variable so it never appears in your source code:

```javascript
const response = await fetch('https://api.vercel.com/v10/projects?limit=1', {
  headers: {
    Authorization: `Bearer ${process.env.VERCEL_TOKEN}`,
  },
});

if (!response.ok) {
  throw new Error(`Vercel API request failed: ${response.status}`);
}

console.log(await response.json());
```

Run the script with `node list-projects.mjs` from the terminal where you exported `VERCEL_TOKEN`. Keep tokens in server-side code only, because anyone who loads a page can read a token shipped to the browser.

## How to use an access token for team requests

Team- and project-scoped tokens already carry their team, and Vercel infers it from the token, so you can leave out the `teamId` parameter. Full-account tokens target your personal account by default and need a `teamId` (or the team's `slug`) to reach a team's resources.

Find your Team ID on the team's **Settings** page under **General**. To list a team's projects with a full-account token, store the ID in `VERCEL_TEAM_ID` and add it to the query string:

```bash
export VERCEL_TEAM_ID="your_team_id_here"

curl "https://api.vercel.com/v10/projects?teamId=$VERCEL_TEAM_ID&limit=1" \
  -H "Authorization: Bearer $VERCEL_TOKEN"
```

The Node.js version adds `teamId` only when `VERCEL_TEAM_ID` is set, which lets one script work with full-account and scoped tokens:

```javascript
const url = new URL('https://api.vercel.com/v10/projects');
url.searchParams.set('limit', '1');

if (process.env.VERCEL_TEAM_ID) {
  url.searchParams.set('teamId', process.env.VERCEL_TEAM_ID);
}

const response = await fetch(url, {
  headers: {
    Authorization: `Bearer ${process.env.VERCEL_TOKEN}`,
  },
});

if (!response.ok) {
  throw new Error(`Vercel API request failed: ${response.status}`);
}

console.log(await response.json());
```

Every other Vercel REST API endpoint follows the same request shape. Between calls, only the endpoint path changes, plus the `teamId` parameter whenever a full-account token targets a team's resources.

## Troubleshooting authentication errors

| Status                  | Cause                                                        | What to check                                                                                                                                              |
| ----------------------- | ------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `401 Unauthorized`      | The API didn't accept the authentication details             | Confirm `VERCEL_TOKEN` is set and the header reads `Authorization: Bearer <token>`                                                                         |
| `403 Forbidden`         | The token doesn't have permission for the requested resource | Check the token's expiration and scope. Full-account tokens targeting a team need `teamId` or `slug`, and project-scoped tokens can't reach other projects |
| `429 Too Many Requests` | The request exceeded a Vercel REST API rate limit            | Reduce the request rate and retry after the limit resets                                                                                                   |

## Frequently asked questions

### Can I see a Vercel access token again after I create it?

No. Vercel shows a token's value only once, when you create it. If you lose a token, create a replacement and delete the old token from the Account Tokens page.

### Can I create a Vercel access token without the dashboard?

Yes. The Vercel CLI creates tokens with `vercel tokens add`, and the [create an auth token](https://vercel.com/docs/rest-api/authentication/create-an-auth-token) endpoint creates them through the REST API. Both accept an optional project ID to create a project-scoped token. The CLI expects the project ID, not the project name:

```bash
vercel tokens add "preview-deploy-bot" --project your_project_id_here
```

Creating tokens through the CLI or REST API requires a full-account token, since team- and project-scoped tokens can't create new tokens.

### How do I revoke a Vercel access token?

Delete the token from the Account Tokens page, or remove it with the Vercel CLI by its token ID:

```bash
vercel tokens ls
vercel tokens rm your_token_id_here
```

Any script or integration using a revoked token stops authenticating, so create and distribute its replacement before you revoke a token that's still in use.

## Next steps

Put your token to work with these related docs:

- [Make your first Vercel API request](https://vercel.com/docs/rest-api/getting-started) with `curl` and the Vercel SDK
  
- [Access tokens](https://vercel.com/docs/accounts/access-tokens) for the full behavior of each scope level
  
- [Vercel REST API](https://vercel.com/docs/rest-api) for every endpoint you can call with a token
  
- [`vercel tokens`](https://vercel.com/docs/cli/tokens) for managing tokens from the command line