Native Integration Flows

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 Storage in the Vercel dashboard sidebar, followed by Create Storage, 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:

• Select storage product
• Select billing plan
• Submit store creation

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.

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.

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.

Customers can use the Vercel dashboard, CLI, or REST API to connect a Native Marketplace resource to Production, Preview, Development, and individual Custom Environments. Vercel stores the selected Custom Environments on the project’s resource connection.

To supply a Preview secret value for Custom Environments, set secrets[].environmentOverrides.preview to a non-empty value. If the Preview override is omitted, Vercel uses the default secrets[].value.

Vercel maps each Custom Environment to preview in provider-facing project connection events and deployment action targets. Vercel removes duplicate target values. These target fields do not include Custom Environment slugs or IDs.

In Project Settings, environment variables provided by the resource apply to the environments selected on the resource connection. Deployment Actions are separate. For a Custom Environment deployment, Vercel uses a resource connection for that Custom Environment when one exists. Otherwise, Vercel uses a Preview connection and can add the environment variables from that connection to the deployment.

Vercel updates the project variables after a connection or secret change, but completed deployments keep their previous values. Create a new deployment to use the updated values.

When an integration user selects the Manage button for a product integration from the Vercel dashboard's Integrations section in the sidebar, 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.

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

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

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

This flow lets an integration user bring a resource that already exists on your platform into their Vercel installation, instead of provisioning a new one. Users start it from the Import Existing option on your integration's marketplace page.

To enable it, set the Import Resource URL in the Integration Console. Connected installations also require a Redirect URL; to enable importing for native marketplace installations, contact Vercel.

When the user starts an import, Vercel redirects their browser to your Import Resource URL with a GET request that includes the following query parameters:

For example, your Import Resource URL receives a request like this:

GET https://example.com/vercel/import?installation_id=icfg_1234567890123&product_id=your_product_slug_here&state=your_state_value_here&return=https%3A%2F%2Fvercel.com%2Fapi%2Fv1%2Fintegrations%2Finstallations%2Fresources%2Fimport%2Fcomplete

1. Authenticate the user on your platform and let them choose the resource to import.
2. Register the resource with Vercel by calling the Import Resource endpoint: PUT /v1/installations/{installation_id}/resources/{resourceId}. The resourceId path parameter is your external ID for the resource. Set ownership to "linked" unless the resource is billed through Vercel (see Linked resources), and include the resource's secrets so Vercel can sync environment variables to connected projects.
3. Redirect the user's browser to the return URL with the following query parameters:

For example:

https://vercel.com/api/v1/integrations/installations/resources/import/complete?installation_id=icfg_1234567890123&resource_id=your_resource_id_here&state=your_state_value_here

Vercel then validates the state parameter (it is single-use and must match the user and installation that started the flow), looks up the imported resource, and redirects the user to the import completion page in the Vercel dashboard.

Resources imported with ownership: "linked" behave differently from resources provisioned through Vercel:

• They are not billed through Vercel.
• Secrets sync and SSO work the same way as for provisioned resources.
• Removing a linked resource from Vercel disconnects it on Vercel's side without calling your Delete Resource endpoint. Contact Vercel if your integration needs the deletion callback for linked resources, for example to revoke credentials your server created for the import.

This flow applies to the products in the Experimentation category, enabling providers to display feature flags in the Vercel dashboard.

This flow applies to integration products in the Experimentation category. It enables providers to push the necessary configuration data for resolving flags and experiments into a Global Config on the team's account, ensuring near-instant resolution.

Global Config Syncing is an optional feature that providers can enable for their integration. Users can opt in by enabling it for their installation in the Vercel Dashboard.

Users can enable this setting either during the integration's installation or later through the installation's settings page. Providers must handle this setting in their Provision Resource and Update Resource endpoints.

The presence of protocolSettings.experimentation.edgeConfigId in the payload indicates that the user has enabled the setting and expects their Global Config to be used.

Afterward, providers can use the Global Config Syncing endpoint to push their data into the user's Global Config.

Once the data is available, users can connect the resource to a Vercel project. Doing so will add an EXPERIMENTATION_CONFIG environment variable containing the Global Config connection string along with the provider's secrets.

Users can then use the appropriate adapter provided by the Flags SDK, which will utilize the Global Config.

When a Vercel user claims deployment ownership with the Claim Deployments feature, storage integration resources associated with the project can also be transferred. To facilitate this transfer for your storage integration, use the following flows.

Vercel users can transfer ownership of an integration installation if they meet these requirements:

• They must have DELETE permissions on the source team (Owner role)
• They must also be a valid owner or member of the destination team

This ensures only authorized users can transfer billing responsibility between teams.

This flow describes how a claims generator (e.g. AI agent) provisions a provider resource and connects it to a Vercel project. Before the flow begins, the claims generator must have installed the provider's integration. The flow results in the claims generator's Vercel team having a provider resource installed and connected to a project under that team.

This flow describes how a claims generator initiates a request to transfer provider resources, with Vercel as an intermediary. The flow results in the claims generator obtaining a claim code from Vercel and the provider issuing a provider claim ID for the pending resource transfer.

Example for CreateResourceTransfer request (Vercel API):

curl --request POST \
  --url https://api.vercel.com/projects/<project_id>/transfer-request\?teamId\=<team_id> \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{}'

CreateResourceTransfer response with a claim code:

{ "code": "c7a9f0b4-4d4a-45bf-b550-2bfa34de1c0d" }

This flow describes how a Vercel user accepts a resource transfer request when they visit a Vercel URL sent by the claims generator. The URL includes a unique claim code that initiates the transfer to a target team the user owns. Vercel and the provider verify and execute the transfer, resulting in the ownership of the project and associated resources being transferred to the user.

Vercel calls your integration server twice during the accept flow:

Step 1: Verify the transfer

Endpoint: GET /v1/installations/{installationId}/resource-transfer-requests/{providerClaimId}/verify

Verify that the transfer is still valid. Check that:

• The provider claim ID exists and hasn't expired
• The resources still exist
• The transfer hasn't already been completed

Response:

{
  "valid": true,
  "billingPlan": {
    "id": "plan_xyz",
    "cost": 10.00
  }
}

If the transfer requires a new billing plan for the target team, include it in the response.

Step 2: Accept the transfer

Endpoint: POST /v1/installations/{installationId}/resource-transfer-requests/{providerClaimId}/accept

Complete the transfer by:

• Updating resource ownership from the claims generator to the target user
• Linking resources to the target installation
• Invalidating the provider claim ID

Request body:

{
  "targetInstallationId": "icfg_target123",
  "targetTeamId": "team_target456"
}

Response:

{
  "success": true
}

If transfers fail, check these common issues:

• Invalid provider claim ID: The claim ID might have expired or already been used. Generate a new transfer request.
• Missing installation: The target team must have your integration installed. Prompt the user to install it first.
• Billing plan conflicts: If the transfer requires a billing plan change, ensure the target team can accept it.
• Resource ownership: Verify that resources belong to the source installation before transferring.