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:
| Scope | Access |
|---|---|
| Full Account | Acts on your personal account and every team you belong to. The Scope dropdown labels this option "Full Account". |
| Team | Limited to a single team. The token can read and write that team's resources across all of its projects. |
| Project | Limited 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.
Create a Vercel API access token from your personal account's Account Tokens page:
- Enter a descriptive token name.
- 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.
- Choose an expiration and select Create.
- 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.
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.
Enter a descriptive name for the token so you can identify it later.
Open the Scope dropdown and select the team that owns the project. Clicking the team drills into its list of projects.
Select the project you want the token to be limited to.
Choose an expiration and select Create.
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.
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:
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:
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:
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:
| Response | Cause | Fix |
|---|---|---|
403 with "invalidToken": true | The 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": true | The 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 token | A full-account token targets your default team unless you specify a team. | Add teamId or slug to the request. |
| A project-scoped token is denied | Project-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. |
429 | The 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
projectIdin the request body to scope the token to a project. - Vercel CLI, where
vercel tokensmanages tokens from the command line. Avercel loginsession can't create tokens, so pass an existing access token to the CLI with the--tokenoption or theVERCEL_TOKENenvironment variable. To create a project-scoped token, pass a team-scoped token for the team that owns the project and runvercel 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.
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:
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.
Was this helpful?