Skip to content
Last updated on March 9, 2023
6 min read

Creating an Integration

Learn how to create your own integration for internal or public use with Vercel.

You can create an integration for internal or public use. Privately means that the Integration is unlisted and you can share it with just your team, or publicly you can distribute it in the Integrations Marketplace, through a direct link, or through the Deploy button.

To create an Integration, open the Integrations tab on your Vercel dashboard, click the Integrations Console button, and choose Create.

Create a new integration from the console.
Create a new integration from the console.
Create a new integration from the console.

In this section, you are asked to fill out the basic details of your Integration which include fields like Name, URL Slug, Descriptions, Logo, and Media content.

In addition to these fields, you need to configure four other important settings for the Integration.

This URL should point to your site to serve the UI during installation and call the Vercel API. For any integration to work, you must create an HTTP endpoint called the Redirect URL that will:

  • Exchange a code for a Vercel API access token.
  • Render a responsive user interface inside a popup window during installation.
  • Allow users to provision a new or connect existing projects in your system with their Vercel Projects.
  • Upon completion, redirect the user back to Vercel.

See the Marketplace, External, or Deploy button sections below to learn which query parameters are available during installation.

Note: For local development and testing, you can specify a URL on localhost.

When installing an integration via the Marketplace, the Redirect URL displays a page that allows a user to setup the integration on your side. Once finished, redirect the user to the provided next URL that will close the popup window and the user can proceed with the flow.

These are the query parameters attached to the Redirect URL:

The External Flow is useful if you're building a mobile app or wish to start the installation flow from your side instead of from the Marketplace. In this case, redirect the user to the following URL to start the installation process from your side:

example-redirect-url

https://vercel.com/integrations/:slug/new

Where :slug is the name you added in the integration profile settings.

With External installation, you can pass the state query parameter:

Key
Required
Description
Example
state
No
Random string to be passed back upon completion. It is used to protect against CSRF attacks.
xyzABC123

With the Redirect URL, you can use the following query parameters:

When installing via Deploy Button, the Redirect URL displays a page that allows you to setup the integration on your side. Once finished, you redirect the user to the provided next URL which will close the popup window and the user can proceed with the flow.

These are the query parameters we attach to the Redirect URL:

If the Integration is already installed in the selected scope during the Deploy Button flow, the Redirect URL will be called with the most recent configurationId. Please make sure to store configurationId along with an access token such that if an existing configurationId was passed, you could retrieve the corresponding access token.

When you create a new integration, you are asked to select multiple API Scopes that your integration needs. These scopes will help you access the Vercel API. These scopes can be configured for permissions like Read and Read/Write as per your requirements.

Select API Scopes for your integration.
Select API Scopes for your integration.
Select API Scopes for your integration.

With your integration, you can listen for events on the Vercel Platform via Webhooks. See the Webhooks docs to learn more.

To allow the developer to configure an installed integration, you can specify a Configuration URL. This URL is used for the Configure Button on each Configuration page. Clicking this button will redirect the developer to your specified URL with a configurationId query parameter. See Interacting with Configurations to learn more.

Note: If you don't specify a Configuration URL, all developers will see a Website button instead of a Configure button at the top of the configuration page. The Website button links to the website URL you specified on integration settings.

Once you have created your Integration, you can see it listed on the Integrations Developer Console.

Inside your Integration, click the "View Integration" button to preview the live URL for your integration in the Marketplace. This URL can be shared with anyone who wants to install and use your Integration.

This live URL has the following format:

example-url

https://vercel.com/integrations/:slug

Where :slug is the name you added in the integration profile settings.

Note: Your Integration will not be visible on the Integrations Marketplace until it's approved by Vercel. To submit your Integration for review, follow theReview guidelines.

Integrations allow you to extend the capabilities of Vercel and connect your application with third-party services. We've created starter kits like Next.js Commerce, Virtual Events, and Platforms that use integrations to help you get started quickly.

Using an integration does not require a starter kit, but it can be helpful to enable developers to get started with your integration quickly.

Note: Integrations must follow all the requirements listed before submitting for approval.