VercelVercel
Marketplace Partner API

Marketplace Partner API

Learn how to implement Partner API endpoints on your integration server. Vercel calls these endpoints to manage installations, handle user actions, and process billing for your native integration.

Select an endpoint from the sidebar to view complete documentation with request/response schemas, authentication requirements, and code examples.

How it works

When a user interacts with your integration, Vercel calls your Partner API endpoints on your integration server. You implement these endpoints to handle:

  • Installation lifecycle — Create, update, and delete installations when users add or remove your integration
  • Resource management — Provision and configure resources when users connect projects or add configuration
  • Billing operations — Handle invoice creation, usage reporting, and payment processing
  • User authentication — Validate and process user-initiated actions

Your integration also calls Vercel API endpoints to interact with Vercel resources like projects, deployments, and environment variables. See Native Integration Flows to understand how these APIs work together.

Authentication

Vercel authenticates requests to your Partner API endpoints using the methods below. You must validate authentication on every request to ensure requests come from Vercel.

User Authentication

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:
{
  "type": "object",
  "properties": {
    "iss": {
      "type": "string",
      "enum": [
        "https://marketplace.vercel.com"
      ]
    },
    "aud": {
      "type": "string",
      "description": "The integration ID. Example: \"oac_9f4YG9JFjgKkRlxoaaGG0y05\""
    },
    "type": {
      "type": "string",
      "enum": [
        "access_token",
        "id_token"
      ],
      "description": "The type of the token: id_token or access_token."
    },
    "account_id": {
      "type": "string"
    },
    "sub": {
      "type": "string",
      "description": "Denotes the User who is making the change (matches `/^account:[0-9a-fA-F]+:user:[0-9a-fA-F]+$/`)"
    },
    "installation_id": {
      "type": "string",
      "description": "The ID of the installation. Example: \"icfg_9bceb8ccT32d3U417ezb5c8p\""
    },
    "user_id": {
      "type": "string"
    },
    "user_role": {
      "type": "string",
      "enum": [
        "ADMIN",
        "USER"
      ],
      "description": "The `ADMIN` 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."
    },
    "user_email": {
      "type": "string",
      "description": "The user's verified email address. For this property to have a value, your Marketplace integration must be opted in. Please reach out to Vercel Support to request access. Without access, this property will be undefined."
    },
    "user_name": {
      "type": "string",
      "description": "The user's real name"
    },
    "user_avatar_url": {
      "type": "string",
      "description": "The user's public avatar URL"
    }
  },
  "required": [
    "iss",
    "aud",
    "account_id",
    "sub",
    "installation_id",
    "user_id",
    "user_role"
  ],
  "additionalProperties": false
}

System Authentication

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:
{
  "type": "object",
  "properties": {
    "iss": {
      "type": "string",
      "enum": [
        "https://marketplace.vercel.com"
      ]
    },
    "sub": {
      "type": "string",
      "description": "Denotes the Account (or Team) who is making the change (matches `/^account:[0-9a-fA-F]+$/`), possibly null"
    },
    "aud": {
      "type": "string",
      "description": "The integration ID. Example: \"oac_9f4YG9JFjgKkRlxoaaGG0y05\""
    },
    "type": {
      "type": "string",
      "enum": [
        "access_token",
        "id_token"
      ],
      "description": "The type of the token: id_token or access_token."
    },
    "installation_id": {
      "type": "string",
      "nullable": true,
      "description": "The ID of the installation. Example: \"icfg_9bceb8ccT32d3U417ezb5c8p\""
    },
    "account_id": {
      "type": "string"
    }
  },
  "required": [
    "iss",
    "sub",
    "aud",
    "installation_id",
    "account_id"
  ],
  "additionalProperties": false
}

Security best practices

  • Verify token signatures — Always validate OIDC token signatures using Vercel's OIDC configuration
  • Check claims — Verify the aud claim matches your integration ID and the sub claim identifies the authenticated user or account
  • Validate user roles — For user authentication, always validate the user's role before performing actions

Base URL

Configure your integration's base URL when you create your integration in the Integration Console. All Partner API endpoints are relative to this base URL.

https://your-integration-server.com/api

Required endpoints

Every integration must implement these core endpoints:

  • Upsert Installation — Called when a user installs or updates your integration. You receive installation details and an access token for calling Vercel's API
  • Delete Installation — Called when a user uninstalls your integration. Clean up resources and revoke access
  • Update Resource — Called when a user connects a project or adds configuration. Provision resources based on user settings

Next steps

  • Select an endpoint from the sidebar to view implementation details
  • Review Native Integration Flows to understand the complete integration lifecycle
  • See the Vercel API reference for endpoints you'll call from your integration