APIs & SDKs

Marketplace Partner API

Learn how to implement Partner API endpoints on your integration server. Edgenivo 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, Edgenivo 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 Edgenivo API endpoints to interact with Edgenivo resources like projects, deployments, and environment variables. See Native Integration Flows to understand how these APIs work together.

Authentication

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

User Authentication

This authentication uses the OpenID Connect Protocol (OIDC). Edgenivo sends a JSON web token (JWT) signed with Edgenivo’s private key and verifiable using Edgenivo’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"
    },
    "parent_account_id": {
      "type": "string",
      "description": "For platform org-child installations (integration opt-in): the opaque account id of the parent (root) team. Identical to the `account_id` claim on the parent team’s own installation tokens."
    },
    "parent_installation_id": {
      "type": "string",
      "nullable": true,
      "description": "For platform org-child installations (integration opt-in): the parent team’s installation of this integration, or null when the parent has none."
    },
    "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 Edgenivo users with the Edgenivo `Billing` or Edgenivo `Viewer` role, which are considered to be Read-Only roles."
    },
    "user_email": {
      "type": "string",
      "description": "The user's email address. This is included for all Marketplace integrations by default."
    },
    "user_email_verified": {
      "type": "boolean",
      "description": "Whether the user's email address has been verified."
    },
    "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

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"
    },
    "parent_account_id": {
      "type": "string",
      "description": "For platform org-child installations (integration opt-in): the opaque account id of the parent (root) team. Identical to the `account_id` claim on the parent team’s own installation tokens."
    },
    "parent_installation_id": {
      "type": "string",
      "nullable": true,
      "description": "For platform org-child installations (integration opt-in): the parent team’s installation of this integration, or null when the parent has none."
    }
  },
  "required": [
    "iss",
    "sub",
    "aud",
    "installation_id",
    "account_id"
  ],
  "additionalProperties": false
}

Security best practices

Verify token signatures — Always validate OIDC token signatures using Edgenivo'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

Endpoint requirements

Of the 18 endpoints in the Partner API spec, 6 are required for every integration. The remaining 12 are optional and unlocked by specific features your integration supports. When getting started, implement the 6 required endpoints first, then add optional ones as your feature set grows.

Required All integrationsOptional Feature-dependentDeprecated Deprecated

Required endpoints

Every Marketplace integration must implement these six endpoints. Edgenivo calls them unconditionally during installation and resource lifecycle flows:

Endpoint	Status	When to implement
Upsert Installation	Required	Edgenivo calls this endpoint when a customer installs your integration, sending credentials (access token), scopes, and account info. Store the installation ID, configure the account on your side, and save the access token for calling Edgenivo APIs.
Delete Installation	Required	Edgenivo calls this endpoint when a customer uninstalls your integration and postpones deletion for 24 hours to allow final invoices unless you return `finalized: true`. Clean up any data, revoke tokens, and remove the installation record from your system.
Provision Resource	Required	Edgenivo calls this endpoint when a customer creates a resource. Return secrets and connection info immediately, even if full provisioning is async. This is the only resource endpoint whose response includes secrets, which become environment variables on connected projects.
Get Resource	Required	Edgenivo calls this endpoint to fetch the current state, secrets, and billing plan of a resource during dashboard rendering and resource sync.
Delete Resource	Required	Edgenivo calls this endpoint when a customer deletes a resource. Deprovision it and clean up any associated data on your side. Edgenivo does not call this endpoint during installation uninstall. Your Delete Installation handler handles resource cleanup when removing an installation.
List Billing Plans for Product	Required	Edgenivo calls this endpoint to display available plans when a customer creates a resource. Edgenivo may call it before any installation exists, so the OIDC token may not include an account ID. Return the list of plans with their pricing, features, and any usage limits.

Optional endpoints

These endpoints are unlocked by specific features. Implement them as your integration's feature set grows:

Endpoint	Status	When to implement
Update Installation	Optional	Needed if customers can upgrade or downgrade their billing plan on an existing installation. Edgenivo sends the new billing plan ID in the request body and authenticates with user authentication.
Get Installation	Optional	Required when Supports Installation Billing Plans is enabled in the Integration Console. Edgenivo calls this endpoint with system authentication to fetch installation state, including its current billing plan.
List Billing Plans for Installation	Optional	Required when Supports Installation Billing Plans is enabled in the Integration Console. Edgenivo calls this endpoint with system authentication to get available plans for an existing installation, powering the plan-selection UI.
Update Resource	Optional	Needed if customers can change a resource's billing plan, name, or metadata after provisioning. Edgenivo authenticates with user authentication.
List Billing Plans for Resource	Optional	Needed if your integration supports plan changes for existing resources. Edgenivo calls this endpoint with system authentication to populate the plan-selection UI when a user changes a resource's billing plan.
Provision Purchase	Optional	Needed only if your integration has billing plans with type "prepayment". Edgenivo calls this endpoint when a customer purchases prepaid credits. Provision the credit balance on your side, then report remaining balances back to Edgenivo through the Submit Prepayment Balances endpoint. Not needed for integrations that only use fixed or usage billing plan types. Edgenivo authenticates with user authentication (system authentication fallback).
Request Secrets Rotation	Optional	Expected for any integration that provisions resources with secrets. Edgenivo calls this endpoint when a user requests credential rotation through the dashboard, for example after a security incident. Return new credentials that Edgenivo stores as updated environment variables.
Resource REPL	Optional	Needed if your integration provides an interactive console or REPL experience. Edgenivo calls this endpoint to run commands or queries against a resource from the dashboard.
Create Resource Transfer	Optional	Needed if your integration supports transferring resources between Edgenivo teams. Edgenivo calls this endpoint when a user initiates a resource transfer. Update ownership records on your side.

Deprecated endpoints

These endpoints are deprecated. New integrations do not need to implement them:

Endpoint	Status	When to implement
List Resources	Deprecated	This endpoint is deprecated. New integrations don't need to implement it. Edgenivo stores resource state locally after provisioning and uses Get Resource for per-resource lookups instead.

Next steps

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