Learn how to authenticate and use the Marketplace API to set up your integration server for the base URL.
When a customer uses your integration, the following two APIs are used for interaction and communication between the user, Vercel and the provider integration:
Review Native Integration Concepts and Native Integration Flows to learn more.
This authentication uses the OpenID Connect Protocol (OIDC). Vercel sends a JSON web token (JWT) signed with Vercel’s private key and verifiable using Vercel’s public JSON Web Key Sets (JWKS) available here.
User Auth OIDC token claims schema:
https://marketplace.vercel.com/^account:[0-9a-fA-F]+:user:[0-9a-fA-F]+$/)ADMIN | USERADMIN role, by default, is provided to users capable of installing integrations, while the USER role can be granted to Vercel users with the Vercel Billing or Vercel Viewer role, which are considered to be Read-Only roles.This authentication uses the OpenID Connect Protocol (OIDC). Vercel sends a JSON web token (JWT) signed with Vercel’s private key and verifiable using Vercel’s public JSON Web Key Sets (JWKS) available here.
System Auth OIDC token claims schema:
https://marketplace.vercel.com/^account:[0-9a-fA-F]+$/), possibly nullcredentials field of the request body of the Upsert Installation call.https://api.vercel.com/oauth/authorizehttps://api.vercel.com/oauth/access_tokenVercel initiates SSO as part of the Open in Provider flow.
Flow
code and other parametersThe SSO request to the redirectLoginUrl will include the following authentication parameters:
mode. The mode of the OAuth authorization is always set to sso.code: The OAuth authorization code.state: The state parameter that was passed in the OAuth authorization request.The code and state 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:
product_id: The ID of the provider's productresource_id: The ID of the provider's resourceproject_id: The ID of the Vercel project, for instance, when the resource is connected to the Vercel project. Example: "prj_ff7777b9".experimentation_item_id: See Experimentation flow.invoice_id: The ID of the provider's invoicepath: Indicates the area where the user should be redirected to after SSO. The possible values are: "billing", "usage", and "support".url: 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 sso: URLs, such as Notification.href, 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.
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:
https://vercel.com/sso/integrations/{URLSlug}/{installationId}?{query}
Where:
URLSlug: The unique identifier for your integration in the Vercel Integrations MarketplaceinstallationId: The ID of the specific installation for the userquery: Optional query parameters to include additional informationExample
Let's say you have an AWS integration with the following details:
URLSlug: aws-marketplace-integration-demoinstallationId: icfg_PSFtkFqr5djKRtOkNtOHIfSdresource_id=123456The constructed URL would look like this:
https://vercel.com/sso/integrations/aws-marketplace-integration-demo/icfg_PSFtkFqr5djKRtOkNtOHIfSd?resource_id=123456
Flow
/v1/installations/{installationId}| Name | Description | Type |
|---|---|---|
installationId | The ID of target installation. Example: "icfg_9bceb8ccT32d3U417ezb5c8p" | string |
The installation was created successfully
/v1/installations/{installationId}| Name | Description | Type |
|---|---|---|
installationId | The ID of target installation. Example: "icfg_9bceb8ccT32d3U417ezb5c8p" | string |
The installation
/v1/installations/{installationId}| Name | Description | Type |
|---|---|---|
installationId | The ID of target installation. Example: "icfg_9bceb8ccT32d3U417ezb5c8p" | string |
The installation was updated successfully
/v1/installations/{installationId}| Name | Description | Type |
|---|---|---|
installationId | The ID of target installation. Example: "icfg_9bceb8ccT32d3U417ezb5c8p" | string |
Installation deleted successfully
/v1/installations/{installationId}/resources| Name | Description | Type |
|---|---|---|
installationId | The ID of target installation. Example: "icfg_9bceb8ccT32d3U417ezb5c8p" | string |
Return the newly provisioned resource
ready | pending | suspended | resumed | uninstalled | error/v1/installations/{installationId}/resources| Name | Description | Type |
|---|---|---|
installationId | The ID of target installation. Example: "icfg_9bceb8ccT32d3U417ezb5c8p" | string |
Return a list of Resources for a given Installation
/v1/installations/{installationId}/resources/{resourceId}| Name | Description | Type |
|---|---|---|
installationId | The ID of target installation. Example: "icfg_9bceb8ccT32d3U417ezb5c8p" | string |
resourceId | Partner-provided resource ID | string |
Return the resource
ready | pending | suspended | resumed | uninstalled | error/v1/installations/{installationId}/resources/{resourceId}| Name | Description | Type |
|---|---|---|
installationId | The ID of target installation. Example: "icfg_9bceb8ccT32d3U417ezb5c8p" | string |
resourceId | Partner-provided resource ID | string |
Return the updated resource
ready | pending | suspended | resumed | uninstalled | error/v1/installations/{installationId}/resources/{resourceId}| Name | Description | Type |
|---|---|---|
installationId | The ID of target installation. Example: "icfg_9bceb8ccT32d3U417ezb5c8p" | string |
resourceId | Partner-provided resource ID | string |
Resource deleted successfully
No content
/v1/installations/{installationId}/resources/{resourceId}/repl| Name | Description | Type |
|---|---|---|
installationId | The ID of target installation. Example: "icfg_9bceb8ccT32d3U417ezb5c8p" | string |
resourceId | Partner-provided resource ID | string |
Return result of running REPL command
/v1/products/{productSlug}/plansVercel sends a request to the partner to return quotes for different billing plans for a specific Product.
Note: You can have this request triggered by Vercel before the integration is installed when the Product is created for the first time. In this case, OIDC will be incomplete and will not contain an account ID.
| Name | Description | Type |
|---|---|---|
productSlug | The partner-specific ID/slug of the product. Example: "redis" | string |
Return a list of billing plans
/v1/installations/{installationId}/resources/{resourceId}/plans| Name | Description | Type |
|---|---|---|
installationId | The ID of target installation. Example: "icfg_9bceb8ccT32d3U417ezb5c8p" | string |
resourceId | Partner-provided resource ID | string |
Return a list of billing plans for a resource
/v1/installations/{installationId}/plans| Name | Description | Type |
|---|---|---|
installationId | The ID of target installation. Example: "icfg_9bceb8ccT32d3U417ezb5c8p" | string |
Return a list of billing plans for an installation
/v1/installations/{installationId}/billing/provisionprepayment.| Name | Description | Type |
|---|---|---|
installationId | The ID of target installation. Example: "icfg_9bceb8ccT32d3U417ezb5c8p" | string |
Return a timestamp alongside a list of balances for the installation with the most up-to-date values
https://api.vercel.com/v1/installations/{integrationConfigurationId}/account| Name | Description | Type |
|---|---|---|
integrationConfigurationId | None | string |
https://api.vercel.com/v1/installations/{integrationConfigurationId}/member/{memberId}| Name | Description | Type |
|---|---|---|
integrationConfigurationId | None | string |
memberId | None | string |
ADMIN | USERADMIN role, by default, is provided to users capable of installing integrations, while the USER role can be granted to Vercel users with the Vercel Billing or Vercel Viewer role, which are considered to be Read-Only roles."https://api.vercel.com/v1/installations/{integrationConfigurationId}/eventslist-resources and other read APIs to get the new state.resource.updated event should be dispatched when any state of a resource linked to Vercel is modified by the partner.installation.updated event should be dispatched when an installation's billing plan is changed via the provider instead of Vercel.resource.updated event to notify Vercel to update the resource in Vercel’s datastores.resource.updated event to notify Vercel to update the resource's status in Vercel's datastores.| Name | Description | Type |
|---|---|---|
integrationConfigurationId | None | string |
No content
https://api.vercel.com/v1/installations/{integrationConfigurationId}/resources| Name | Description | Type |
|---|---|---|
integrationConfigurationId | None | string |
https://api.vercel.com/v1/installations/{integrationConfigurationId}/resources/{resourceId}| Name | Description | Type |
|---|---|---|
integrationConfigurationId | The ID of the integration configuration (installation) the resource belongs to | string |
resourceId | The ID provided by the 3rd party provider for the given resource | string |
ready | pending | suspended | resumed | uninstalled | errorhttps://api.vercel.com/v1/installations/{integrationConfigurationId}/resources/{resourceId}| Name | Description | Type |
|---|---|---|
integrationConfigurationId | None | string |
resourceId | None | string |
No content
https://api.vercel.com/v1/installations/{integrationConfigurationId}/resources/{resourceId}| Name | Description | Type |
|---|---|---|
integrationConfigurationId | None | string |
resourceId | None | string |
https://api.vercel.com/v1/installations/{integrationConfigurationId}/billingcredentials.access_token we provided in the Upsert Installation body to authorize this request.| Name | Description | Type |
|---|---|---|
integrationConfigurationId | None | string |
No content
https://api.vercel.com/v1/installations/{integrationConfigurationId}/billing/invoicescredentials.access_token we provided in the Upsert Installation body to authorize this request. | Name | Description | Type |
|---|---|---|
integrationConfigurationId | None | string |
https://api.vercel.com/v1/installations/{integrationConfigurationId}/billing/invoices/{invoiceId}| Name | Description | Type |
|---|---|---|
integrationConfigurationId | None | string |
invoiceId | None | string |
pending | scheduled | invoiced | paid | notpaid | refund_requested | refundedhttps://api.vercel.com/v1/installations/{integrationConfigurationId}/billing/invoices/{invoiceId}/actions| Name | Description | Type |
|---|---|---|
integrationConfigurationId | None | string |
invoiceId | None | string |
No content
https://api.vercel.com/v1/installations/{integrationConfigurationId}/billing/balancecredentials.access_token we provided in the Upsert Installation body to authorize this request.| Name | Description | Type |
|---|---|---|
integrationConfigurationId | None | string |
No content
https://api.vercel.com/v1/installations/{integrationConfigurationId}/products/{integrationProductIdOrSlug}/resources/{resourceId}/secrets| Name | Description | Type |
|---|---|---|
integrationConfigurationId | None | string |
integrationProductIdOrSlug | None | string |
resourceId | None | string |
No content
https://api.vercel.com/v1/installations/{integrationConfigurationId}/resources/{resourceId}/secrets| Name | Description | Type |
|---|---|---|
integrationConfigurationId | None | string |
resourceId | None | string |
No content
https://api.vercel.com/v1/integrations/sso/tokencode parameter. The provider then calls the SSO Token Exchange endpoint with the sent code and receives the OIDC token. They log the user in based on this token and redirects the user back to the Vercel account using deep-link parameters included the redirectLoginUrl. Providers should not persist the returned id_token in a database since the token will expire. See Authentication with SSO for more details.https://api.vercel.com/v1/installations/{integrationConfigurationId}/resources/{resourceId}/experimentation/items| Name | Description | Type |
|---|---|---|
integrationConfigurationId | None | string |
resourceId | None | string |
The items were created
No content
https://api.vercel.com/v1/installations/{integrationConfigurationId}/resources/{resourceId}/experimentation/items/{itemId}| Name | Description | Type |
|---|---|---|
integrationConfigurationId | None | string |
resourceId | None | string |
itemId | None | string |
The item was updated
No content
https://api.vercel.com/v1/installations/{integrationConfigurationId}/resources/{resourceId}/experimentation/items/{itemId}| Name | Description | Type |
|---|---|---|
integrationConfigurationId | None | string |
resourceId | None | string |
itemId | None | string |
The item was deleted
No content
https://api.vercel.com/v1/installations/{integrationConfigurationId}/resources/{resourceId}/experimentation/edge-config| Name | Description | Type |
|---|---|---|
integrationConfigurationId | None | string |
resourceId | None | string |
The Edge Config data
https://api.vercel.com/v1/installations/{integrationConfigurationId}/resources/{resourceId}/experimentation/edge-config| Name | Description | Type |
|---|---|---|
integrationConfigurationId | None | string |
resourceId | None | string |
The Edge Config was updated
https://api.vercel.com/v1/integrations/sso/tokencode parameter. The provider then calls the SSO Token Exchange endpoint with the sent code and receives the OIDC token. They log the user in based on this token and redirects the user back to the Vercel account using deep-link parameters included the redirectLoginUrl. Providers should not persist the returned id_token in a database since the token will expire. See Authentication with SSO for more details.You can receive the following events:
marketplace.invoice.created: the invoice was created and sent to the customermarketplace.invoice.paid: the invoice was paidmarketplace.invoice.notpaid: the invoice was not paid after a grace period
marketplace.invoice.refunded: the invoice was refundedGet Integration Resources, Get Integration Resource, and Delete Integration Resource have been added to the APIs available for providers to call on Vercel.ADMIN and USER roles now have clearer explanations in the User Security section, associated with the user_role field.Installation.notification field can now be returned in the "Get Installation" API response, allowing for an active installation notification.environmentOverrides field per secret, allowing for different values on a per-environment level.Provision Purchase endpoint now accepts "System" authentication, as well as "User" authentication. System authentication is used for automatic balance top-ups.Upsert Installation endpoint now provides a new request field account: AccountInfo, that can be used in place of calling Get Account Info for the initial installation. The Get Account Info endpoint should continue to be called for all other use cases.Update Resource Secrets By Id endpoint now accepts partial: boolean request field. When set to true, this call allows updating only the specified secrets, leaving the rest of the secrets unchanged.Provision Purchase endpoint, and Submit Prepayment Balances endpoint.externalId property from the external-id query parameter in the Deploy Button flow.{billingPlan: BillingPlan} in the response. This is useful for installation level billing.{finalized: true} to signal that the installation can be removed immediately. Otherwise, the installation will wait for up to 12hr for any pending billing data to be submitted.BillingPlan.maxResources field.AccountInfo.url field to the "Get Account Information" API.BillingPlan.scope attribute that determines installation or resource level billing for a billing plan.resourceId for each item.discounts fields.Resource.billingPlan is no longer required when the integration has installation-level billing enabled. If installation-level billing is not enabled in the Integration Console and this property is missing, the response will be treated as an error.user_email to the User Authentication JWT claims.REPL endpoint.BillingPlan.requiredPolicies? and ProvisionResourceRequest.acceptedPolicies fields until further notice. The only policies required/accepted for now are for the InstallIntegrationRequest.Resource.notification field for an optional active resource notification.BillingPlan.quote field is replaced with more generic BillingPlan.details and BillingPlan.cost fields.BillingPlan.paymentMethodRequired field as added to indicate free plans.BillingItem in the "Send invoice billing and usage data" endpoint is removed as not correct./v1/integrations/marketplace/installations namespace were shortened to /v1/installations. The old, longer namespaced routes will continue to work as expected.BillingPlan.type value of "invoice" has been changed to "subscription".Resource.billingPlan type has been changed from string (for a plan ID) to a BillingPlan structure with the complete plan information. billingPlan: string for a plan ID has been changed to billingPlanId: string for consistency.BillingPlan.maxProducts has been renamed to maxResources.Was this helpful?