Reference

Native Integration Flows

Learn how information flows between the integration user, Vercel, and the integration provider for Vercel native integrations.
Table of Contents

As a Vercel integration provider, when you create a native product integration, you need to set up the integration server and use the Vercel marketplace Rest API to manage the interaction between the integration user and your product.

The following diagrams help you understand how information flows in both directions between the integration user, Vercel and your native integration product for each key interaction between the integration user and the Vercel dashboard.

When a Vercel user, who wants to install a provider native integration, selects the Storage tab of the Vercel dashboard, followed by Create Database, they are taken through the following steps to provide the key information required for the provider to be able to create a product for this user.

After reviewing the flow diagram below, explore the sequence for each step:

Submit Store Creation

View store
metadata

Update metadata

Submit store
details

Start store
provisioning

View store
details

Select Billing Plan

Get plans for selected product

View plans

Select plan

Select Storage Product

Yes

Browse storage

Select Product

First time user?

Create Account

No

Understanding the details of each step will help you set up the installation section of the integration server.

When the integration user selects a storage provider product, an account is created for this user on the provider's side if the account does not exist. If that's the case, the user is presented with the Accept Terms modal.

Provider IntegrationVercel PlatformVercel DashboardUserProvider IntegrationVercel PlatformVercel DashboardUserThe Accept Terms Modal is shown only once. Once the Terms are accepted and the account created,it is skipped in future Create Store flows for this user.Vercel sends an access_token to the Provider hereto enable the Provider to make requests to the Vercel API on behalf of the installation.Providers are expected to store this token for future use as it does not expireIf the provider is usinginstallation-level billing plans a default plan must be assignedin provider systems (default "free")Click Create DatabaseShow Browse Storage ModalSelect Storage Provider and click ContinueShow Accept Terms ModalClick Accept and ContinueCreate AccountPUT /v1/installations/{installationId}Upsert requesting userUpsert installation201 response

Using the installation id for this product and integration user, the Vercel dashboard presents available billing plans for the product. The integration user then selects a plan from the list which is updated on every user input change.

Provider IntegrationVercel PlatformVercel DashboardUserProvider IntegrationVercel PlatformVercel DashboardUserThis response can contain installation or resource level billing plansThe rendered form uses the product's Metadata Schema to define the form fields that collect input from the userloop[Every time the user makes a change in an input field]Show Create Database ModalFetch Billing PlansGET /v1/installations/{installationId}/plans200 GetBillingPlans ResponseRender Billing Plans in form inside ModalUpdates a form input fieldFetch Billing PlansGET /v1/installations/{installationId}/plans200 GetBillingPlans ResponseRender billing plans in form inside ModalSelect billing plan and click Continue

After confirming the plan selection, the integration user is presented with information fields that the integration provider specified in the metadata schema section of the integration settings. The user updates these fields and submits the form to initiate the creation of the store for this user on the provider platform.

Provider IntegrationVercel PlatformVercel DashboardUserProvider IntegrationVercel PlatformVercel DashboardUserIncludes the data collected from the user input fields.If the installation-level billing plan is received,the provider should update the installation billing plan and provision the resource.This is where the provider should start the asynchronous provisioning of the resource. The credentials of the resource need to be known before provisioning is completed and returned in this request.Send the resource.updated event when provisioning the store is complete.This happens asynchronously after the initial provisioning request.Show store metadata inside modalUpdate store metadata and click CreateCreate storePOST /v1/installations/{installationId}/resources200 ProvisionResourceResponseShow store detail pageFetch storeGET /v1/installations/{installationId}/resources/{resourceId}200 GetResourceResponseRender store inside detail pageResource provisioned successfullyPOST /v1/installations/{integrationConfigurationId}/events ResourceUpdatedEvent

When an integration user selects the Manage button for a product integration from the Vercel dashboard's Integrations tab, they are taken to the installation settings page for that integration. When they select the Open in [provider] button, they are taken to the provider's dashboard page in a new window. The diagram below describes the flow of information for authentication and information exchange when this happens.

Provider IntegrationVercel PlatformVercel DashboardUserProvider IntegrationVercel PlatformVercel DashboardUserOpen Store Detail PageClick "Open in [Provider]" ButtonOpens new tab to loginRedirectUriwith code and resource_id query paramsPOST /v1/integrations/sso/token code200 SsoExchangeResponseLog user inRender Provider Dashboard andtarget resource_id if specified

This flow happens when a provider edits information about a resource in the provider's system.

Provider IntegrationVercel PlatformUserProvider IntegrationVercel PlatformUserUpdates Resource AttributePOST /v1/installations/:installation_id/eventsResourceUpdatedEventGET /v1/installations/:id/resources/:id200 GetResourceResponseUpdate Resource

This flow happens when a user who has installed the product integration edits information about it on the Vercel dashboard.

Provider IntegrationVercel PlatformVercel DashboardUserProvider IntegrationVercel PlatformVercel DashboardUserUpdates Resource AttributeSends UpdatePATCH /v1/installations/:id/resources/:idUpdate Resource200 UpdateResourceResponse

This flow happens when a provider rotates the credentials of a resource in the provider system.

Provider IntegrationVercel PlatformUserProvider IntegrationVercel PlatformUserRotate CredentialsPUT /v1/installations/:id/product/:id/resource/:id/secretsResourceUpdatedEventUpdate Resource Projects’Environment Variables

Vercel will update the environment variables of projects connected to the resource but will not automatically redeploy the projects. The user must redeploy them manually.

Last updated on October 2, 2024

Interested in talking to

a Vercel product expert?

Schedule a call