Using the Integrations REST API

Learn how to authenticate and use the Integrations REST API to build your native integration with Vercel.

When a customer uses your integration, the following two APIs are used for interaction and communication between the user, Vercel and the provider integration:

• Vercel calls the provider API: You implement the Vercel Marketplace Partner API endpoints on your integration server. Vercel calls them to manage resources, handle installations, and process billing.
• The provider calls the Vercel API: Vercel provides these endpoints. You call them from your integration server to interact with Vercel's platform.

When building your integration, you'll implement the partner endpoints and call the Vercel endpoints as needed.

See the Native Integration Flows to understand how these endpoints work together.

The authentication method depends on whether Vercel is calling the integration provider's API or the provider is calling Vercel's API.

There are two authentication methods available:

• User authentication: The user initiates the action. You receive a JWT token that identifies the user making the request.
• System authentication: Your integration performs the action automatically. You use account-level OpenID Connect (OIDC) credentials to authenticate.

System authentication uses OIDC tokens that represent your integration account, not a specific user. This lets you make API calls to Vercel without requiring user interaction.

• Automatic balance top-ups for prepayment plans
• Background synchronization tasks
• Automated resource management
• Any operation that should run without user action
• Installation cleanup operations when the Vercel account is deleted

• User-initiated actions
• Operations that require user consent
• Actions tied to a specific user's context

• Verify the OIDC token signature and claims: Always validate the token signature using Vercel's OIDC configuration. Check the claim matches your integration ID, and the claim identifies the authenticated user or account.
• For user authentication always validate the user's role.

Review the user authentication and system authentication specifications to help you implement each method.

When your integration calls Vercel's API, you authenticate using an access token. You receive this token during the installation process when you call the Upsert Installation API. The response includes a object with an that you use as a bearer token for subsequent API calls.

You can also use OAuth2 to obtain access tokens for user-specific operations.

Vercel initiates SSO as part of the Open in Provider flow.

1. Vercel sends the user to the provider redirectLoginUrl, with the OAuth authorization and other parameters
2. The provider calls the SSO Token Exchange, which validates the SSO request and returns OIDC and access tokens
3. The user gains authenticated access to the requested resource.

Parameters:

The SSO request to the redirectLoginUrl will include the following authentication parameters:

• . The mode of the OAuth authorization is always set to .
• : The OAuth authorization code.
• : The state parameter that was passed in the OAuth authorization request.

The and parameters will be passed back to Vercel in the SSO Token Exchange request.

Additionally, the SSO request to the redirectLoginUrl may include the following optional context parameters:

• : The ID of the provider's product
• : The ID of the provider's resource
• : The ID of the deployment check, when the resource is associated with a deployment check. Example: "chk_abc123".
• : The ID of the Vercel project, for instance, when the resource is connected to the Vercel project. Example: "prj_ff7777b9".
• : See Experimentation flow.
• : The ID of the provider's invoice
• : The URL of the pull request in the Vercel project, when known in the context. Example: .
• : Indicates the area where the user should be redirected to after SSO. The possible values are: "billing", "usage", "onboarding", and "support".
• : The provider-specific URL to redirect the user to after SSO. Must be validated by the provider for validity. The data fields that are allowed to provide URLs, such as , will automatically propagate the provided URL in this parameter.

The provider should match the most appropriate part of their dashboard to the user's context.

Using SSO with API responses:

You can trigger SSO by using URLs in your API responses. When users click these links, Vercel initiates the SSO flow before redirecting them to your platform. The prefix works in any URL field that supports it, such as installation notification links or resource URLs.

Format:

When a user clicks a link with an URL:

1. Vercel initiates the SSO flow
2. Your provider validates the SSO request via the SSO Token Exchange
3. The user is redirected to the target URL with authenticated access

Example with notifications:

The integration provider can initiate the SSO process from their side. This helps to streamline the authentication process for users coming from the provider's platform and provides security when a user attempts to access a resource managed by a Vercel Marketplace integration.

To initiate SSO, an integration provider needs to construct a URL using the following format:

• : The unique identifier for your integration in the Vercel Integrations Marketplace
• : The ID of the specific installation for the user
• : Optional query parameters to include additional information

Example:

Let's say you have an AWS integration with the following details:

• :
• :
• Additional parameter:

The constructed URL would look like this:

Flow:

1. The provider constructs and redirects the user to the SSO URL
2. Vercel validates the SSO request and confirms user access
3. After successfully validating the request, Vercel redirects the user back to the provider using the same flow described in the Vercel Initiated SSO
4. The user gains authenticated access to the requested resource

Get details about team members who have access to an installation. Use this endpoint to retrieve member information for access control, audit logs, or displaying member details in your integration.

To retrieve information about a specific team member associated with an installation, use the endpoint.

• - The installation ID
• - The member ID

Members can have the following roles:

• - Full access to the installation and its resources
• - Limited access, can use resources but can't modify settings

Check the member's role to determine what actions they can perform below.

Installation notifications appear in the Vercel dashboard to alert users about important information or actions needed for their installation. You can set notifications when creating or updating installations.

Update the notification field using the endpoint as shown below:

Use different notification types to indicate severity:

• - Informational message (default)
• - Warning that requires attention
• - Error that needs immediate action

The notification field supports special URLs that trigger Single Sign-On before redirecting users to your destination. This ensures users are authenticated before accessing resources on your platform.

Format:

When a user clicks a notification link with an URL:

1. Vercel initiates the SSO flow (as described in Vercel initiated SSO)
2. Your provider validates the SSO request via the SSO Token Exchange
3. The user is redirected to the target URL with authenticated access

Example:

Use URLs in notification links when they point to resources that require authentication on your platform. For public pages or general information, use regular HTTPS URLs.

Remove a notification by setting it to :

You can find the value of the notification field by calling the endpoint as shown below:

You can receive billing events with webhooks to stay informed about invoice status changes and take appropriate actions.

You can receive the following events:

• : The invoice was created and sent to the customer
• : The invoice was paid
• : The invoice was not paid after a grace period
• : The invoice was refunded

You should verify webhook signatures to ensure requests come from Vercel. Integration webhooks use your Integration Secret (also called Client Secret) from the Integration Console for signature verification. Follow the Securing webhooks section of the Webhooks API Reference to learn more.

You can implement handlers for each billing event type to manage invoice lifecycle and resource access.

When an invoice is created, you can prepare your systems for billing or send notifications.

Event:

When an invoice is paid, activate resources or update billing status.

Event:

When an invoice isn't paid after the grace period, suspend resources or take other actions.

Event:

When an invoice is refunded, update records and handle resource access accordingly.

Event: