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.
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.
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:
https://vercel.com/integrations/:slug/newWhere :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.
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.
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:
https://vercel.com/integrations/:slugWhere :slug is the name you added in the integration profile settings.
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.