Skip to content

Vercel API

Lean how to use the Vercel API to build your Integrations and work with Redirect URLs.

The Vercel API is a REST-styled API that empowers you to gauge the capabilities of the entire Vercel platform including the Integrations.

When building an integration with Vercel, you can request Vercel Access Tokens to authenticate and use the Vercel API. You must provide an API token through the Authorization header.

When installing an Integration, users get redirected to your defined Redirect URL. Since there are several ways of installing an integration, different query parameters are attached.

One of these is the code parameter. This code is valid for 30 minutes and can be only exchanged once for an (long lived) access token.

Note: To avoid CORS and security issues, don't use Access Tokens on the client side. Use only on an API or backend.

Since Integrations are always installed on a certain scope, it's essential to understand the scope of your Access Tokens as well.

Make sure you append the teamId query parameter to each API request, if your integration is installed on a team. See Accessing Resources Owned by a Team for more details.

The response of your code exchange request includes a team_id property. If team_id is not null, you know that this integration was installed on a team.

In addition to these Vercel API helps your Integrations to interact with the following:

You can exchange the code parameter for an Access Token using the following API endpoint:

{`POST https://api.vercel.com/v2/oauth/access_token`}

Pass the following values to request body in the form of application/x-www-form-urlencoded.

Key
Type
Required
Description
client_id
ID
Yes
ID of your application.
client_secret
String
Yes
Secret of your application.
code
String
Yes
The code you received.
redirect_uri
String
Yes
The Redirect URL you configured on the Integration Console.
{`curl -X POST ${API_ENDPOINT}/v2/oauth/access_token \\
 -d "client_id=oac_4GViITbjKesSmZ658unqfNA8&client_secret=EOBPvZuBYAtb3SbYo8H1iWFP&code=jMIukZ1DBCKXHje3X14BCkU0&redirect_uri=https://example.com/oauth" \\
 -H "Content-Type: application/x-www-form-urlencoded"
`}

You'll receive a JSON response containing the value of an access_token:

{
  "token_type": "Bearer",
  "access_token": "xEbuzM1ZAJ46afITQlYqH605",
  "installation_id": "icfg_ijgU3GzRxyz7nGpwwsSmbNkI",
  "user_id": "2tUzTmv4ljvFVHifEf9TGdpH",
  "team_id": null
}
Note: A request can only be made once with the same code.

Each installation of your integration is stored and tracked as a configuration.

Sometimes it makes sense to fetch the configuration in order to get more insights about the current scope or the projects your integration has access to.

To see which endpoints are available, visit our API Documentation about Configurations.

Warning: If an owner(s) of an integration leaves the team that's responsible for the integration, the integration will be flagged as disabled. The team will receive an email to take action (transfer ownership) within 30 days, otherwise the integration will be deleted.

When integration configurations are disabled:

  • Any API requests will fail with a 403 HTTP status code and a code of integration_configuration_disabled
  • We continue to send project.created, project.removed and integration-configuration.removed webhooks, as these will allow the integration configuration to operate correctly when re-activated. All other webhook delivery will be paused
  • Log drains will not receive any logs

Deployments made with Vercel are grouped into Projects. This means that each deployment is assigned a name and is grouped into a project with other deployments using that same name.

Using the Vercel API, you can modify Projects that the Integration has access to. Here are some examples:

When building a Vercel Integration, you may want to expose an API token or a configuration URL for deployments within a Project.

You can do so by Creating a Project Environment Variable using the API.

Note: Environment Variables created by an Integration will display the Integration's logo.

See the following API reference documentation for how to utilize it:

When creating integrations the following scopes can be updated within the Integration Console:

Note: For updating the domain of a project write permissions are required for bothproject and domain.
Scope
Description
integration-configuration
Interact with the installation of your integration
deployment
Interact with deployments
deployment-check
Verify deployments with Checks
edge-config
Create and manage Edge Configs and their tokens
project
Access project details and settings
project-env-vars
Create and manage integration-owned project environment variables
global-project-env-vars
Create and manage all account project environment variables
team
Access team details
user
Get information about the current user
log-drain
Create and manage log drains to forward logs
domain
Manage and interact with domains and certificates

As the Vercel API evolves, you'll need to update your scopes based on your integration's endpoint usage.

Confirming Scope changes.

Additions and upgrades always require a review and confirmation. To ensure this, every affected user and team owner will be informed via email to undergo this process. Please make sure you provide a meaningful, short, and descriptive note for your changes.

Scope removals and downgrades won't require user confirmation and will be applied immediately to confirmed scopes and pending requested scope changes.

User and Teams will always confirm all pending changes with one confirmation. That means that if you have requested new scopes multiple times over the past year, the users will see a summary of all pending changes with their respective provided note.

Once a user confirms these changes, scopes get directly applied to the installation. You will also get notified via the new integration-configuration.scope-change-confirmed event.

When using the Vercel API with Integrations, you might come across some errors which you can address immediately.

To avoid CORS issues, make sure you only interact with the Vercel API on the server side.

Since the token grants access to resources of the Team or Personal Account, you should never expose it on the client side.

For more information on using CORS with Vercel, see How can I enable CORS on Vercel?.

Ensure you are not missing the teamId query parameter. teamId is required if the integration installation is for a Team. See Knowing the Scope of Your Access Token for more details.