Skip to content
Docs

Create a connector

POSThttps://api.vercel.com/v1/connect/connectors
Create a connector and optionally link it to a project. Use type with complete provider data, or use service with connectionMethod so Connect can supply the type, endpoints, templates, and defaults.
https://api.vercel.com/v1/connect/connectors
const response = await fetch('https://api.vercel.com/v1/connect/connectors?teamId=string&slug=string', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "data": {
      "serverUrl": "https://example.com",
      "serverConfig": {
        "issuer": "string",
        "authorization_endpoint": "string",
        "token_endpoint": "string",
        "userinfo_endpoint": "string",
        "jwks_uri": "https://example.com",
        "jwks": {
          "keys": [
            {
              "kty": "string",
              "kid": "example_id",
              "use": "sig",
              "key_ops": [],
              "alg": "string"
            }
          ]
        },
        "revocation_endpoint": "string",
        "introspection_endpoint": "string",
        "end_session_endpoint": "string",
        "device_authorization_endpoint": "string",
        "registration_endpoint": "string",
        "response_types_supported": [],
        "token_endpoint_auth_methods_supported": [],
        "token_endpoint_auth_signing_alg_values_supported": [],
        "scopes_supported": [],
        "grant_types_supported": [],
        "authorization_grant_profiles_supported": [],
        "identity_chaining_requested_token_types_supported": [],
        "response_modes_supported": [],
        "subject_types_supported": [],
        "id_token_signing_alg_values_supported": [],
        "id_token_encryption_alg_values_supported": [],
        "id_token_encryption_enc_values_supported": [],
        "claim_types_supported": [],
        "claims_supported": [],
        "code_challenge_methods_supported": [],
        "prompt_values_supported": [],
        "claims_parameter_supported": "true",
        "request_parameter_supported": "true",
        "request_uri_parameter_supported": "true",
        "require_request_uri_registration": "true",
        "service_documentation": "string",
        "op_policy_uri": "https://example.com",
        "op_tos_uri": "https://example.com",
        "logo_uri": "https://example.com",
        "client_id_metadata_document_supported": "true",
        "authorization_details_types_supported": []
      },
      "clientId": "example_id",
      "clientName": "Example Name",
      "clientSecret": "string",
      "tokenEndpointAuthMethod": "string",
      "responseType": "string",
      "pkceRequired": "true",
      "codeChallengeMethod": "string",
      "userAuthorization": {
        "enabled": "true",
        "scopes": []
      },
      "refreshTokens": {
        "enabled": "true"
      },
      "clientCredentials": {
        "enabled": "true",
        "scopes": []
      },
      "forwardedClaims": {
        "idToken": []
      },
      "defaultAudience": "string",
      "defaultResource": "string",
      "defaultTokenExpiresIn": "123",
      "authorizationUrlParams": "value",
      "jwtBearer": {
        "enabled": "true",
        "scopes": [],
        "sub": "string",
        "iss": "string",
        "aud": "string",
        "additionalClaims": "value",
        "ttl": "123",
        "useClientCredentials": "true"
      },
      "clientAssertion": {
        "type": "string",
        "ttl": "123",
        "claims": "value"
      }
    },
    "icon": "string",
    "backgroundColor": "string",
    "accentColor": "string",
    "type": "string",
    "service": "string",
    "connectionMethod": "string",
    "params": "value",
    "target": "string",
    "uid": "example_id",
    "name": "Example Name",
    "projectId": "example_id",
    "environments": [],
    "triggers": "true",
    "triggerType": "string",
    "triggerVerificationInput": "value",
    "triggerRegistrationInput": "value",
    "triggerDestination": {
      "projectId": "example_id",
      "path": "string"
    },
    "events": []
  }),
});


const data = await response.json();
console.log(data);
Response
{
  "accentColor": "string",
  "appTokens": {
    "crossInstallation": "false",
    "permissionsUrl": "https://example.com",
    "requiresReinstallation": "false",
    "scopes": [],
    "supportedAuthorizationDetails": [],
    "supportsRefinement": "false",
    "supportsResources": "false"
  },
  "backgroundColor": "string",
  "clientUrl": "https://example.com",
  "connectionMethod": "string",
  "createdAt": "123",
  "createdBy": {
    "id": "icfg_1234567890",
    "type": "user"
  },
  "creationMode": "managed",
  "defaultInstallationId": "example_id",
  "devsite": "string",
  "displayName": "Example Name",
  "docsite": "string",
  "events": [],
  "icon": "string",
  "id": "icfg_1234567890",
  "knownStale": "false",
  "managed": {
    "sync": "false"
  },
  "name": "Example Name",
  "redirectUri": "https://example.com",
  "reinstallAt": "123",
  "service": "string",
  "serviceIcon": "string",
  "supportedSubjectTypes": [],
  "supportsIcon": "false",
  "supportsInstallation": "false",
  "supportsManagedEjection": "false",
  "supportsRevocation": "false",
  "supportsTriggers": "false",
  "target": "string",
  "triggerDestinations": [
    {
      "branch": "string",
      "customEnvironmentId": "example_id",
      "path": "string",
      "projectId": "example_id"
    }
  ],
  "triggers": {
    "enabled": "false"
  },
  "type": "api-key",
  "typeIcon": "string",
  "typeName": "Example Name",
  "uid": "example_id",
  "updatedAt": "123",
  "updatedBy": {
    "id": "icfg_1234567890",
    "type": "user"
  },
  "userTokens": {
    "crossInstallation": "false",
    "manualCredentialInput": "false",
    "scopes": [],
    "supportedAuthorizationDetails": [],
    "supportsRefinement": "false",
    "supportsResources": "false"
  },
  "website": "string"
}
Errors
{
  "error": {
    "code": "string",
    "message": "string"
  }
}

Authentication

AuthorizationbearerToken

Default authentication mechanism

Query parameters

teamIdstringOptional
The team ID that scopes the request. Do not send it with slug. If both are omitted, Vercel uses the team associated with the token or the authenticated user's default team. The request returns 401 if no team can be selected.
slugstringOptional
The team slug that scopes the request. Do not send it with teamId. If both are omitted, Vercel uses the team associated with the token or the authenticated user's default team. The request returns 401 if no team can be selected.

Body

application/json
dataobjectRequired11 variants
iconstringOptional
SHA-1 digest of a PNG or JPEG icon that is at least 640 by 640 pixels. This field does not accept a URL or image bytes.
First compute the digest and upload the raw image with POST /v2/files. Send Content-Length and the same 40-character digest in x-vercel-digest. Then set icon to that digest.
import { createHash } from 'node:crypto';
import { readFile } from 'node:fs/promises';


const VERCEL_TOKEN = process.env.VERCEL_TOKEN;
const connectorId = 'scl_...';
const bytes = await readFile('icon.png');
const digest = createHash('sha1').update(bytes).digest('hex');


await fetch('https://api.vercel.com/v2/files', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${VERCEL_TOKEN}`,
    'Content-Type': 'application/octet-stream',
    'Content-Length': String(bytes.length),
    'x-vercel-digest': digest,
  },
  body: bytes,
});


await fetch(`https://api.vercel.com/v2/connect/connectors/${connectorId}`, {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${VERCEL_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ icon: digest }),
});
backgroundColorstringOptional
Branding background color (6-digit hex, for example
accentColorstringOptional
Branding accent color (6-digit hex, for example
typestringRequired
Connector implementation type for full configuration. Known types: api-key, discord, github, linear, linq, microsoft-entra, oauth, photon, salesforce, sendblue, slack, snowflake, snowflake-wif. Optional when service and connectionMethod select the type.
servicestringOptional
Service slug or URL for which the connector is used. Required when connectionMethod is set. Service alone does not enable preset configuration.
connectionMethodstringOptional
Connection method slug of the service. Use it with service to select preset configuration.
paramsobjectOptional
Values for the selected connection method's template fields. Requires connectionMethod.
targetstringOptional
Which of the service's targets this connector is for. Requires "connectionMethod" and must be one that method serves. Optional.
uidstringOptional
Optional team-scoped unique identifier for the connector. If omitted or empty, Connect generates a value.
namestringOptional
Connector name. The value is trimmed and cannot contain control characters. If omitted or empty, the project name is used. A name or projectId is required. API key connectors require name.
projectIdstringOptional
Project to connect during creation. If environments is omitted, the connection uses development, preview, and production.
environmentsarrayOptional
Environments for the project connection. Requires projectId. Use one or more built-in environment names or stable custom environment IDs that belong to the project. Duplicate values are accepted and removed.
triggersbooleanOptional
Whether the triggers are enabled for this connector.
triggerTypestringOptional
Trigger driver type. Resolved automatically from the known service connection method when not provided. Only set when using the newly decoupled triggers resolution flow.
triggerVerificationInputobjectOptional
Plaintext verification inputs, validated by the trigger driver and encrypted into stored triggerData. An empty object makes no changes.
triggerRegistrationInputobjectOptional
Additional registration inputs, validated by the trigger driver. Requires triggers: true. Shared verification credentials are read from triggerData.
triggerDestinationobjectOptional3 variants
eventsarrayOptional
Default trigger events for this connector.

Response

201The connector was created.
accentColorstringOptional
Hex accent color (e.g., #000000) for branding.
appTokensobjectOptional
App-token capabilities and known grants for the connector.
backgroundColorstringOptional
Hex background color (e.g., #000000) for branding.
clientUrlstringOptional
Provider-side URL for viewing or managing the resource represented by the connector. The destination can be an app, account, phone line, or service instance, depending on the connector type.
connectionMethodstringOptional
The connection method this connector was created from, when the create request named one.
createdAtnumberRequired
Creation time in epoch milliseconds.
createdByobjectOptional2 variants
creationModestringOptional
How the connector row was originally created. New create paths stamp this explicitly; older rows may omit it.
defaultInstallationIdstringOptional
Installation used when a token request does not specify an installation.
devsitestringOptional
Developer website for the connected service.
displayNamestringRequired
Human-readable connector name.
docsitestringOptional
Developer documentation for the connected service.
eventsarrayOptional
Known events this connector subscribes to (e.g. Slack bot events, GitHub webhook events). Names are type-specific and validated by the managed-create flow when forwarded to the third-party service.
iconstringOptional
Connector branding icon. SHA-1 hash that resolves to the uploaded icon through the Vercel avatar service. Consumers render this with https://vercel.com/api/www/avatar/{icon}.
idstringRequired
Stable scl_ connector ID. Use this value directly in {connector}.
knownStalebooleanOptional
Whether the connector is known to have been edited since the app package it publishes to the provider was last built, so that package no longer matches it. Absent when it was not computed, or when the connector type publishes no such package. Derived on every read rather than marked at edit time, so reverting an edit clears it. Only reported by connector types that publish a package a user has to re-publish by hand — Microsoft Teams today.
managedobjectOptional
Managed connector metadata exposed without leaking the manager connector or installation identifiers.
namestringRequired
Connector name within the owning team.
redirectUristringOptional
Redirect URI registered with the third-party service for this connector, if any. Used by startAuthorization/startInstallation to replay the exact URI back to the provider's token endpoint. Absent on connectors created before this field was introduced; those callers fall back to the https://connect.vercel.com/callback default.
reinstallAtnumberOptional
Time when this connector started requiring reinstallation because an installation-affecting app-token grant changed.
servicestringRequired
Best-effort identifier of the third-party service this connector represents, independent of type. Examples: 'slack', 'mcp.linear.app', and 'auth.example.com'. Always present in API responses.
serviceIconstringOptional
Provider logo from the known-service registry, matched by service. Often an SVG data URL. Absent when the service is not in the registry.
supportedSubjectTypesarrayRequired
Token subject types supported by the connector.
supportsIconobjectRequired
Whether the connector icon can propagate to the provider.
supportsInstallationbooleanRequired
Whether the connector supports an installation flow.
supportsManagedEjectionbooleanOptional
Whether this managed connector can disconnect from its manager.
supportsRevocationbooleanRequired
Whether Connect can revoke tokens for this connector.
supportsTriggersbooleanRequired
Whether this connector type supports trigger webhooks. Derived from the type definition; indicates that triggers and triggerDestinations may be meaningful for this connector.
targetstringOptional
Which of the service's products/surfaces this connector points at.
triggerDestinationsarrayOptional
Destinations that incoming triggers should be forwarded to. Limited to 3 entries. Set the initial destination with triggerDestination during creation. Replace the complete set with PATCH /v1/connect/connectors/{connector}/trigger-destinations.
triggersobjectOptional
Incoming trigger configuration. Only present when enabled.
typestringRequired
Connector implementation type.
typeIconstringOptional
Icon identifier supplied by the connector type.
typeNamestringRequired
Human-readable name of the connector type.
uidstringRequired
Team-scoped UID. URL-encode this value before using it in {connector}.
updatedAtnumberRequired
Last update time in epoch milliseconds.
updatedByobjectOptional2 variants
userTokensobjectOptional
User-token capabilities and known grants for the connector.
websitestringOptional
Public website for the connected service.

Errors

400One of the provided values in the request body is invalid.
errorobjectRequired
Error details.
401The request is not authorized.
errorobjectRequired
Error details.
403You do not have permission to access this resource.
errorobjectRequired
Error details.
404The requested resource was not found.
errorobjectRequired
Error details.
409The request conflicts with the current resource state.
errorobjectRequired
Error details.
410The requested resource is no longer available.
errorobjectRequired
Error details.
422The request cannot be completed in the current state.
errorobjectRequired
Error details.
500An internal error occurred.
errorobjectRequired
Error details.
501Error
502A dependency returned an invalid or unsuccessful response.
errorobjectRequired
Error details.
504Error