Skip to content
Docs

Access tokens

Vercel access tokens authenticate requests to the Vercel REST API and the Vercel CLI on your behalf. You create and manage them on the Account Tokens page, under the Settings area of your account, and you can also create them without the dashboard using the REST API or the CLI.

A token's value appears only once, at creation, so copy it then and store it somewhere secure because you cannot retrieve it again afterward. Every token carries a scope that determines which resources it can reach. This page explains the three scoping levels and walks through creating a project-scoped token, which limits a token to a single project.

When you create a token, you choose how far its access reaches. Vercel supports three levels:

ScopeAccess
Full AccountActs on your personal account and every team you belong to. The Scope dropdown labels this option "Full Account".
TeamLimited to a single team. The token can read and write that team's resources across all of its projects.
ProjectLimited to a single project within a team. The token can only read and write resources belonging to that one project.

A project-scoped token denies any request to another project, to a user-level resource, or to a team-level resource. This keeps jobs, tools, and workflows constrained to the projects they need rather than granting them the entire team or your full account.

Some teams require you to enable two-factor authentication or SAML before you can create tokens scoped to them. If a team enforces this, the dashboard tells you so when you select it.

Create a Vercel API access token from your personal account's Account Tokens page:

  1. Enter a descriptive token name.
  2. Open Scope and choose the resources the token needs. Select Full Account for personal account access, or select a team to limit access to that team. If the team opens a project list, select All Projects for team access or an individual project for project access.
  3. Choose an expiration and select Create.
  4. Copy the token and store it securely. Vercel shows the value only once.

Choose the narrowest scope that supports your task. For a walkthrough of project access, see Project-scoped access token.

This section covers creating a project-scoped access token from the dashboard.

  • A Vercel account.
  • Membership in the team that owns the project you want to scope the token to.
  • Two-factor authentication enabled on your account, if the target team requires it.
  1. In the scope selector at the top left of the dashboard's navigation bar, make sure you are viewing your personal account rather than a team. Then go to the Account Tokens page, also found under the Settings area of your account.

  2. Enter a descriptive name for the token so you can identify it later.

  3. Open the Scope dropdown and select the team that owns the project. Clicking the team drills into its list of projects.

  4. Select the project you want the token to be limited to.

    Selecting All Projects instead of an individual project creates a team-scoped token rather than a project-scoped one.

  5. Choose an expiration and select Create.

  6. Copy the token now. Personal access tokens begin with the prefix vcp_, and the value will not be shown again.

Pass the token as a Bearer token in the Authorization header of your request.

terminal
curl "https://api.vercel.com/v9/projects" \
  -H "Authorization: Bearer vcp_xxxxxxxxxxxxxxxxxxxxxxxx"

Listing projects with a scoped access token

Team- and project-scoped tokens do not require the teamId query parameter or the team slug on API requests. Vercel infers the team and project from the token's scope, so you can omit those parameters. Full-account tokens still need ?teamId= when targeting a specific team's resources.

To list deployments, send a request to GET /v7/deployments. Store your token in the VERCEL_ACCESS_TOKEN environment variable, then run:

terminal
curl "https://api.vercel.com/v7/deployments" \
  -H "Authorization: Bearer $VERCEL_ACCESS_TOKEN"

The response contains a deployments array and pagination information. A full-account token targets your default team by default. A team- or project-scoped token targets the resources in its scope.

For a full-account token targeting a team, set VERCEL_TEAM_ID to the team's ID from team settings, then include teamId in the request:

terminal
curl "https://api.vercel.com/v7/deployments?teamId=$VERCEL_TEAM_ID" \
  -H "Authorization: Bearer $VERCEL_ACCESS_TOKEN"

You can also make the request from server-side JavaScript:

list-deployments.mjs
const url = new URL('https://api.vercel.com/v7/deployments');
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_ACCESS_TOKEN}`,
  },
});
 
if (!response.ok) {
  throw new Error(`Vercel API request failed: ${response.status}`);
}
 
const { deployments } = await response.json();
console.log(deployments);

This prints the deployments accessible to the token and selected team. Keep the token in server-side environment variables rather than client-side code.

If a request with a token fails, read the error object in the response body to find the cause:

ResponseCauseFix
403 with "invalidToken": trueThe token is wrong, expired, or deleted.Check that the header reads Authorization: Bearer <token> and that the token still appears on the Account Tokens page. If you've lost the token, create a new one.
403 with "missingToken": trueThe request has no Authorization header, or the header isn't in the form Bearer <token>. A common cause is an environment variable that's empty in the current shell.Check that the header reads Authorization: Bearer <token>. Run echo "${VERCEL_ACCESS_TOKEN:+set}" to confirm the variable is set, then send the request from the same shell.
A team's resources are missing, or the request is denied, with a full-account tokenA full-account token targets your default team unless you specify a team.Add teamId or slug to the request.
A project-scoped token is deniedProject-scoped tokens can't access other projects, team-level resources, or user-level resources.Use a team-scoped token, or a project-scoped token for the project you're requesting.
429The request exceeded a REST API rate limit.Reduce your request rate and retry after the limit resets.

You can create tokens without the dashboard through two paths.

  • REST API, where the create an auth token endpoint accepts an optional projectId in the request body to scope the token to a project.
  • Vercel CLI, where vercel tokens manages tokens from the command line. A vercel login session can't create tokens, so pass an existing access token to the CLI with the --token option or the VERCEL_TOKEN environment variable. To create a project-scoped token, pass a team-scoped token for the team that owns the project and run vercel tokens create <TOKEN_NAME> --project <PROJECT_ID>. The command takes the team from the token's scope, so a full-account token doesn't work with --project.

Creating a full-account token through the CLI or API, or a team-scoped token through the API, requires a full-account token. A team-scoped token can create only project-scoped tokens for projects in its team. A project-scoped token cannot mint new tokens.

The Vercel REST API returns when a request last used a token, and your team's Activity Log shows which events happened on the team and the user involved in each one.

The Get Auth Token Metadata endpoint, GET /v5/user/tokens/{tokenId}, returns the token's activeAt field, the timestamp in milliseconds of the most recent request that used the token. Pass current as the tokenId to read the metadata for the token that authenticates the request. With your token in the VERCEL_ACCESS_TOKEN environment variable, run:

terminal
curl "https://api.vercel.com/v5/user/tokens/current" \
  -H "Authorization: Bearer $VERCEL_ACCESS_TOKEN"

The response contains a token object with activeAt alongside the token's other metadata:

{
  "token": {
    "activeAt": 1234567890123,
    "createdAt": 1234567890123,
    "id": "your_token_id_here",
    "name": "your_token_name_here",
    "type": "token"
  }
}

To check all of your tokens, call the List Auth Tokens endpoint, GET /v6/user/tokens, which returns activeAt for each token in its tokens array. This endpoint requires a Full Account token. It returns tokens in pages. When pagination.next isn't null, pass its value as the until query parameter to request the next page.

The Activity Log, available on all plans, lists the events on a team with the user involved, the type of event, and the time it happened. See Events logged for the events the Activity Log records, or query the same events from the command line with vercel activity.

On Enterprise plans, team members with the owner or security role can use Audit Logs for security review. Audit Logs include Activity Log events and additional audit metadata. You can export Audit Logs as a CSV file for the last 90 days, or forward them to an external destination with Audit Log Drains.

Last updated September 8, 2026

Was this helpful?

supported.