--- title: create-a-connector product: vercel url: /docs/rest-api/connect/create-a-connector canonical_url: "https://vercel.com/docs/rest-api/connect/create-a-connector" last_updated: 2026-08-28 type: reference prerequisites: [] related: - /docs/rest-api summary: Learn about create-a-connector on Vercel. install_vercel_plugin: npx plugins add vercel/vercel-plugin --- # Create a connector ```http POST /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. ## Authentication **bearerToken**: HTTP bearer ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `teamId` | string | No | 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. | | `slug` | string | No | 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. | ## Request body Required: No Content-Type: `application/json` ```json { "type": "object", "description": "Create a connector with full provider configuration or with a known service connection method.", "required": [ "data" ], "properties": { "data": { "description": "Provider configuration. With type, provide the complete configuration for that type. With service and connectionMethod, provide only credentials and preferences; Connect supplies the type, endpoints, templates, and defaults. Other connector types accept an arbitrary object.", "anyOf": [ { "type": "object", "required": [ "clientId" ], "properties": { "serverUrl": { "type": "string", "description": "Authorization server base URL used for discovery." }, "serverConfig": { "type": "object", "description": "Authorization server metadata. Values override discovered metadata. Empty known string fields remove their stored overrides.", "default": {} }, "clientId": { "type": "string", "description": "OAuth client ID assigned by the provider." }, "clientName": { "type": "string", "description": "OAuth client name." }, "clientSecret": { "type": "string", "description": "OAuth client secret.", "writeOnly": true }, "tokenEndpointAuthMethod": { "type": "string", "description": "OAuth token endpoint authentication method. Common values are client_secret_post, client_secret_basic, none, and private_key_jwt. If omitted, Vercel selects a supported method from serverConfig and otherwise uses client_secret_post." }, "responseType": { "type": "string", "description": "OAuth authorization response type. Defaults to code. Other provider-supported values are accepted. An empty string clears the configured type." }, "pkceRequired": { "type": "boolean", "description": "Whether user authorization must use PKCE." }, "codeChallengeMethod": { "type": "string", "description": "PKCE code challenge method. Supported values are S256 and plain. Vercel prefers S256 when the provider supports it. An empty string clears the configured method." }, "userAuthorization": { "type": "object", "description": "User authorization grant settings.", "required": [ "enabled" ] }, "refreshTokens": { "type": "object", "description": "Refresh token settings.", "required": [ "enabled" ] }, "clientCredentials": { "type": "object", "description": "Client credentials grant settings.", "required": [ "enabled" ] }, "forwardedClaims": { "type": "object", "description": "Allow-list of extra claims to propagate, keyed by source (idToken). Only claims named here and present in that source are exposed." }, "defaultAudience": { "type": "string", "description": "Default audience used when a token request omits one. An empty string clears the default." }, "defaultTokenExpiresIn": { "type": "number", "description": "Default token lifetime in seconds to use when the token response omits expires_in.", "minimum": 60 }, "authorizationUrlParams": { "type": "object", "description": "Extra query parameters added to authorization URLs." }, "jwtBearer": { "type": "object", "description": "JWT bearer grant settings." }, "clientAssertion": { "type": "object", "description": "`private_key_jwt` client assertion settings." } } }, { "type": "object", "properties": { "subjectType": { "type": "string", "description": "Which subject the connector issues tokens for. Defaults to \\\"app\\\" (connector-level keys). \\\"user\\\" connectors store no connector-level values; each user supplies their own key during authorization.", "enum": [ "app", "user" ] }, "values": { "type": "array", "description": "Initial API key values stored by the connector." }, "serviceUrls": { "type": "array", "description": "The HTTPS resources the API key authenticates against." } } }, { "type": "object", "required": [ "appId", "appSlug", "appName", "clientId" ], "properties": { "appId": { "type": "integer", "description": "GitHub App numeric ID.", "minimum": 0 }, "appSlug": { "type": "string", "description": "GitHub App slug." }, "appName": { "type": "string", "description": "GitHub App display name." }, "clientId": { "type": "string", "description": "OAuth client ID assigned by GitHub." }, "owner": { "type": "object", "description": "GitHub App owner.", "required": [ "type", "id", "slug" ] }, "clientSecret": { "type": "string", "description": "GitHub App OAuth client secret.", "writeOnly": true }, "privateKeyPem": { "type": "string", "description": "GitHub App private key in PEM format.", "writeOnly": true }, "webhookSecret": { "type": "string", "description": "GitHub App webhook secret.", "writeOnly": true }, "extras": { "type": "object", "description": "Additional provider metadata stored with the connector." } } }, { "type": "object", "required": [ "clientId", "clientSecret" ], "properties": { "appId": { "type": "string", "description": "Linear application ID." }, "appName": { "type": "string", "description": "Linear application name." }, "clientId": { "type": "string", "description": "OAuth client ID assigned by Linear." }, "clientSecret": { "type": "string", "description": "Linear OAuth client secret.", "writeOnly": true }, "webhookSecret": { "type": "string", "description": "Linear webhook verification secret.", "writeOnly": true }, "appScopes": { "type": "array", "description": "OAuth scopes requested for Linear application tokens." }, "userScopes": { "type": "array", "description": "OAuth scopes requested for Linear user tokens." }, "ownerOrganization": { "type": "object", "description": "Linear organization that owns the OAuth application.", "required": [ "id", "slug", "name" ] }, "application": { "type": "object", "description": "Linear OAuth application metadata.", "required": [ "id", "clientId", "name" ] }, "extras": { "type": "object", "description": "Additional provider metadata stored with the connector." } } }, { "type": "object", "required": [ "apiToken" ], "properties": { "apiToken": { "type": "string", "description": "Linq partner API token for the shared line.", "writeOnly": true }, "phoneNumbers": { "type": "array" } } }, { "description": "(7 more variants — see OpenAPI spec)" } ] }, "icon": { "type": "string", "description": "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.\n\nFirst compute the digest and upload the raw image with [POST /v2/files](https://vercel.com/docs/rest-api/deployments/upload-deployment-files). Send `Content-Length` and the same 40-character digest in `x-vercel-digest`. Then set `icon` to that digest.\n\n```js\nimport { createHash } from 'node:crypto';\nimport { readFile } from 'node:fs/promises';\n\nconst VERCEL_TOKEN = process.env.VERCEL_TOKEN;\nconst connectorId = 'scl_...';\nconst bytes = await readFile('icon.png');\nconst digest = createHash('sha1').update(bytes).digest('hex');\n\nawait fetch('https://api.vercel.com/v2/files', {\n method: 'POST',\n headers: {\n Authorization: `Bearer ${VERCEL_TOKEN}`,\n 'Content-Type': 'application/octet-stream',\n 'Content-Length': String(bytes.length),\n 'x-vercel-digest': digest,\n },\n body: bytes,\n});\n\nawait fetch(`https://api.vercel.com/v2/connect/connectors/${connectorId}`, {\n method: 'PATCH',\n headers: {\n Authorization: `Bearer ${VERCEL_TOKEN}`,\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({ icon: digest }),\n});\n```\n", "pattern": "^[0-9a-fA-F]{40}$" }, "backgroundColor": { "type": "string", "description": "Branding background color (6-digit hex, for example", "pattern": "^#[0-9a-fA-F]{6}$" }, "accentColor": { "type": "string", "description": "Branding accent color (6-digit hex, for example", "pattern": "^#[0-9a-fA-F]{6}$" }, "type": { "type": "string", "description": "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." }, "service": { "type": "string", "description": "Service slug or URL for which the connector is used. Required when connectionMethod is set. Service alone does not enable preset configuration." }, "connectionMethod": { "type": "string", "description": "Connection method slug of the service. Use it with service to select preset configuration.", "maxLength": 64 }, "params": { "type": "object", "description": "Values for the selected connection method's template fields. Requires connectionMethod.", "additionalProperties": { "type": "string", "maxLength": 256 } }, "target": { "type": "string", "description": "Which of the service's targets this connector is for. Requires \\\"connectionMethod\\\" and must be one that method serves. Optional.", "maxLength": 64 }, "uid": { "type": "string", "description": "Optional team-scoped unique identifier for the connector. If omitted or empty, Connect generates a value." }, "name": { "type": "string", "description": "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." }, "projectId": { "type": "string", "description": "Project to connect during creation. If environments is omitted, the connection uses development, preview, and production." }, "environments": { "type": "array", "description": "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.", "items": { "description": "A built-in environment name or the stable env_* ID of a custom environment.", "anyOf": [ { "type": "string", "enum": [ "development", "preview", "production" ] }, { "type": "string", "pattern": "^env_" } ] } }, "triggers": { "type": "boolean", "description": "Whether the triggers are enabled for this connector." }, "triggerDestination": { "description": "Initial trigger destination. Requires triggers to be enabled and a projectId here or at the top level. Connector responses expose the resulting set as triggerDestinations. Replace the complete set with PATCH /v1/connect/connectors/{connector}/trigger-destinations.", "oneOf": [ { "type": "object", "properties": { "projectId": { "type": "string", "description": "Project that receives triggers. During connector creation, omit it to use the top-level projectId.", "minLength": 1 }, "path": { "type": "string", "description": "Route path on the linked project that receives forwarded trigger requests.", "minLength": 1, "maxLength": 2048 } } }, { "type": "object", "required": [ "branch" ], "properties": { "projectId": { "type": "string", "description": "Project that receives triggers. During connector creation, omit it to use the top-level projectId.", "minLength": 1 }, "branch": { "type": "string", "description": "Git branch used to select a preview deployment.", "minLength": 1, "maxLength": 250 }, "path": { "type": "string", "description": "Route path on the linked project that receives forwarded trigger requests.", "minLength": 1, "maxLength": 2048 } } }, { "type": "object", "required": [ "customEnvironmentId" ], "properties": { "projectId": { "type": "string", "description": "Project that receives triggers. During connector creation, omit it to use the top-level projectId.", "minLength": 1 }, "customEnvironmentId": { "type": "string", "description": "Stable custom environment ID that belongs to the destination project.", "pattern": "^env_" }, "path": { "type": "string", "description": "Route path on the linked project that receives forwarded trigger requests.", "minLength": 1, "maxLength": 2048 } } } ] }, "events": { "type": "array", "description": "Default trigger events for this connector.", "items": { "type": "string" } } }, "anyOf": [ { "required": [ "type" ] }, { "required": [ "service", "connectionMethod" ] } ] } ``` ## Example request ### TypeScript ```typescript 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": {}, "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": [], "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", "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", "triggerDestination": { "projectId": "example_id", "path": "string" }, "events": [] }), }); const data = await response.json(); console.log(data); ``` ### Next.js ```typescript 'use server'; export async function callEndpoint() { const response = await fetch('https://api.vercel.com/v1/connect/connectors?teamId=string&slug=string', { method: 'POST', headers: { 'Authorization': `Bearer ${process.env.VERCEL_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": {}, "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": [], "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", "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", "triggerDestination": { "projectId": "example_id", "path": "string" }, "events": [] }), next: { revalidate: 3600 } }); if (!response.ok) { throw new Error('Request failed'); } return response.json(); } ``` ### cURL ```bash curl -X POST 'https://api.vercel.com/v1/connect/connectors?teamId=string&slug=string' \ -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ -H 'Content-Type: application/json' \ -d "{ \"data\": { \"serverUrl\": \"https://example.com\", \"serverConfig\": { \"issuer\": \"string\", \"authorization_endpoint\": \"string\", \"token_endpoint\": \"string\", \"userinfo_endpoint\": \"string\", \"jwks_uri\": \"https://example.com\", \"jwks\": {}, \"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\": [], \"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\", \"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\", \"triggerDestination\": { \"projectId\": \"example_id\", \"path\": \"string\" }, \"events\": [] }" ``` ## Example response ```json { "id": "icfg_1234567890", "uid": "example_id", "defaultInstallationId": "example_id", "createdAt": "123", "updatedAt": "123", "reinstallAt": "123", "createdBy": { "type": "user", "id": "icfg_1234567890" }, "updatedBy": { "type": "user", "id": "icfg_1234567890" }, "creationMode": "managed", "managed": { "sync": "false" }, "type": "api-key", "service": "string", "connectionMethod": "string", "target": "string", "name": "Example Name", "displayName": "Example Name", "clientUrl": "https://example.com", "redirectUri": "https://example.com", "typeName": "Example Name", "typeIcon": "string", "website": "string", "devsite": "string", "docsite": "string", "icon": "string", "backgroundColor": "string", "accentColor": "string", "supportedSubjectTypes": [], "appTokens": { "crossInstallation": "false", "supportsRefinement": "false", "requiresReinstallation": "false", "scopes": [], "supportedAuthorizationDetails": [], "permissionsUrl": "https://example.com" }, "userTokens": { "crossInstallation": "false", "supportsRefinement": "false", "scopes": [], "supportedAuthorizationDetails": [], "manualCredentialInput": "false" }, "supportsInstallation": "false", "supportsRevocation": "false", "supportsTriggers": "false", "supportsIcon": "false", "triggers": { "enabled": "false" }, "events": [], "triggerDestinations": [ { "projectId": "example_id", "customEnvironmentId": "example_id", "branch": "string", "path": "string" } ] } ``` ## Responses ### 201: The connector was created. Content-Type: `application/json` ```json { "type": "object", "description": "Connector created by the request.", "required": [ "createdAt", "displayName", "id", "name", "service", "supportedSubjectTypes", "supportsIcon", "supportsInstallation", "supportsRevocation", "supportsTriggers", "type", "typeName", "uid", "updatedAt" ], "properties": { "id": { "type": "string", "description": "Stable `scl_` connector ID. Use this value directly in `{connector}`." }, "uid": { "type": "string", "description": "Team-scoped UID. URL-encode this value before using it in `{connector}`." }, "defaultInstallationId": { "type": "string", "description": "Installation used when a token request does not specify an installation." }, "createdAt": { "type": "number", "description": "Creation time in epoch milliseconds." }, "updatedAt": { "type": "number", "description": "Last update time in epoch milliseconds." }, "reinstallAt": { "type": "number", "description": "Time when this connector started requiring reinstallation because an installation-affecting app-token grant changed." }, "createdBy": { "description": "Principal that created the connector.", "oneOf": [ { "type": "object", "description": "Principal that originally created the connector — either a Vercel user (interactive dashboard / CLI flow) or a Vercel deployment (OIDC-authenticated project, used by runtime auto-provisioning). See {@link ConnexPrincipal}. Optional: pre-existing rows from before this shape was introduced may carry no attribution at all.", "required": [ "id", "type" ], "properties": { "type": { "type": "string", "description": "Principal kind.", "enum": [ "user" ] }, "id": { "type": "string", "description": "Vercel user ID." } } }, { "type": "object", "description": "Principal that originally created the connector — either a Vercel user (interactive dashboard / CLI flow) or a Vercel deployment (OIDC-authenticated project, used by runtime auto-provisioning). See {@link ConnexPrincipal}. Optional: pre-existing rows from before this shape was introduced may carry no attribution at all.", "required": [ "environment", "id", "type" ], "properties": { "type": { "type": "string", "description": "Principal kind.", "enum": [ "project" ] }, "id": { "type": "string", "description": "Vercel project ID." }, "environment": { "description": "Deployment environment of the project principal." } } } ] }, "updatedBy": { "description": "Principal that most recently updated the connector.", "oneOf": [ { "type": "object", "description": "Principal that most recently mutated the connector. Same shape as {@link createdBy} but tracks the most recent updater, not the original creator. At create time the two fields point at the same principal; they diverge on the first subsequent update.", "required": [ "id", "type" ], "properties": { "type": { "type": "string", "description": "Principal kind.", "enum": [ "user" ] }, "id": { "type": "string", "description": "Vercel user ID." } } }, { "type": "object", "description": "Principal that most recently mutated the connector. Same shape as {@link createdBy} but tracks the most recent updater, not the original creator. At create time the two fields point at the same principal; they diverge on the first subsequent update.", "required": [ "environment", "id", "type" ], "properties": { "type": { "type": "string", "description": "Principal kind.", "enum": [ "project" ] }, "id": { "type": "string", "description": "Vercel project ID." }, "environment": { "description": "Deployment environment of the project principal." } } } ] }, "creationMode": { "type": "string", "description": "How the connector row was originally created. New create paths stamp this explicitly; older rows may omit it.", "enum": [ "managed", "manual" ] }, "managed": { "type": "object", "description": "Managed connector metadata exposed without leaking the manager connector or installation identifiers.", "properties": { "sync": { "type": "boolean", "description": "Whether Vercel synchronizes provider-side configuration.", "enum": [ false, true ] } } }, "type": { "type": "string", "description": "Connector implementation type.", "enum": [ "api-key", "custom", "discord", "github", "linear", "linq", "microsoft-entra", "microsoft-teams", "oauth", "photon", "salesforce", "sendblue", "slack", "snowflake", "snowflake-wif" ] }, "service": { "type": "string", "description": "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." }, "connectionMethod": { "type": "string", "description": "The connection method this connector was created from, when the create request named one." }, "target": { "type": "string", "description": "Which of the service's products/surfaces this connector points at." }, "name": { "type": "string", "description": "Connector name within the owning team." }, "displayName": { "type": "string", "description": "Human-readable connector name." }, "clientUrl": { "type": "string", "description": "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.", "nullable": true }, "redirectUri": { "type": "string", "description": "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." }, "typeName": { "type": "string", "description": "Human-readable name of the connector type." }, "typeIcon": { "type": "string", "description": "Icon identifier supplied by the connector type." }, "website": { "type": "string", "description": "Public website for the connected service." }, "devsite": { "type": "string", "description": "Developer website for the connected service." }, "docsite": { "type": "string", "description": "Developer documentation for the connected service." }, "icon": { "type": "string", "description": "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}`." }, "backgroundColor": { "type": "string", "description": "Hex background color (e.g., `#000000`) for branding." }, "accentColor": { "type": "string", "description": "Hex accent color (e.g., `#000000`) for branding." }, "supportedSubjectTypes": { "type": "array", "description": "Token subject types supported by the connector.", "items": { "type": "string" } }, "appTokens": { "type": "object", "description": "App-token capabilities and known grants for the connector.", "required": [ "crossInstallation", "supportsRefinement" ], "properties": { "crossInstallation": { "type": "boolean", "description": "Whether one app token can be used across installations.", "enum": [ false, true ] }, "supportsRefinement": { "type": "boolean", "description": "Whether callers can narrow app-token grants per request.", "enum": [ false, true ] }, "requiresReinstallation": { "type": "boolean", "description": "True when changing app token grants requires reinstalling the app, so tokens cannot be partitioned independently by requester environment.", "enum": [ false, true ] }, "scopes": { "type": "array", "description": "Known allowed app-level scopes. For Slack this is the bot scope set configured on the app; for OAuth it is the connector's enabled `clientCredentials.scopes` configuration.", "items": { "type": "string" } }, "supportedAuthorizationDetails": { "type": "array", "description": "Supported OAuth authorization-detail type names.", "items": { "type": "string" } }, "permissionsUrl": { "type": "string", "description": "Link to the page on the service where this connector's app-level permissions are declared and granted, when the service has one and it differs from `clientUrl`." } } }, "userTokens": { "type": "object", "description": "User-token capabilities and known grants for the connector.", "required": [ "crossInstallation", "supportsRefinement" ], "properties": { "crossInstallation": { "type": "boolean", "description": "Whether one user token can be used across installations.", "enum": [ false, true ] }, "supportsRefinement": { "type": "boolean", "description": "Whether callers can narrow user-token grants per request.", "enum": [ false, true ] }, "scopes": { "type": "array", "description": "Known allowed user-level scopes. For Slack this is the user scope set configured on the app; for OAuth it is the connector's enabled `userAuthorization.scopes` configuration.", "items": { "type": "string" } }, "supportedAuthorizationDetails": { "type": "array", "description": "Supported OAuth authorization-detail type names.", "items": { "type": "string" } }, "manualCredentialInput": { "type": "boolean", "description": "User authorization is completed by the Connect consent screen submitting a credential instead of an OAuth redirect.", "enum": [ false, true ] } } }, "supportsInstallation": { "type": "boolean", "description": "Whether the connector supports an installation flow.", "enum": [ false, true ] }, "supportsRevocation": { "type": "boolean", "description": "Whether Connect can revoke tokens for this connector.", "enum": [ false, true ] }, "supportsTriggers": { "type": "boolean", "description": "Whether this connector type supports trigger webhooks. Derived from the type definition; indicates that `triggers` and `triggerDestinations` may be meaningful for this connector.", "enum": [ false, true ] }, "supportsIcon": { "description": "Whether the connector icon can propagate to the provider.", "enum": [ false, "maybe", true ] }, "triggers": { "type": "object", "description": "Incoming trigger configuration. Only present when enabled.", "required": [ "enabled" ], "properties": { "enabled": { "type": "boolean", "description": "Whether incoming triggers are enabled for the connector.", "enum": [ false, true ] } } }, "events": { "type": "array", "description": "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.", "items": { "type": "string" } }, "triggerDestinations": { "type": "array", "description": "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`.", "items": { "type": "object", "description": "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`.", "required": [ "projectId" ], "properties": { "projectId": { "type": "string", "description": "Vercel project that receives matching trigger requests." }, "customEnvironmentId": { "type": "string", "description": "Stable custom-environment ID to route this destination to. Mutually exclusive with `branch`; omitted destinations keep the legacy production behavior." }, "branch": { "type": "string", "description": "Git branch used to select a preview deployment." }, "path": { "type": "string", "description": "Route path that receives the forwarded trigger request." } } } } } } ``` ### 400: One of the provided values in the request body is invalid. Content-Type: `application/json` ```json { "type": "object", "description": "Error response returned by a Connect API operation.", "required": [ "error" ], "properties": { "error": { "type": "object", "description": "Error details.", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable error message." } }, "additionalProperties": true } } } ``` ### 401: The request is not authorized. Content-Type: `application/json` ```json { "type": "object", "description": "Error response returned by a Connect API operation.", "required": [ "error" ], "properties": { "error": { "type": "object", "description": "Error details.", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable error message." } }, "additionalProperties": true } } } ``` ### 403: You do not have permission to access this resource. Content-Type: `application/json` ```json { "type": "object", "description": "Error response returned by a Connect API operation.", "required": [ "error" ], "properties": { "error": { "type": "object", "description": "Error details.", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable error message." } }, "additionalProperties": true } } } ``` ### 404: The requested resource was not found. Content-Type: `application/json` ```json { "type": "object", "description": "Error response returned by a Connect API operation.", "required": [ "error" ], "properties": { "error": { "type": "object", "description": "Error details.", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable error message." } }, "additionalProperties": true } } } ``` ### 409: The request conflicts with the current resource state. Content-Type: `application/json` ```json { "type": "object", "description": "Error response returned by a Connect API operation.", "required": [ "error" ], "properties": { "error": { "type": "object", "description": "Error details.", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable error message." } }, "additionalProperties": true } } } ``` ### 410: The requested resource is no longer available. Content-Type: `application/json` ```json { "type": "object", "description": "Error response returned by a Connect API operation.", "required": [ "error" ], "properties": { "error": { "type": "object", "description": "Error details.", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable error message." } }, "additionalProperties": true } } } ``` ### 422: The request cannot be completed in the current state. Content-Type: `application/json` ```json { "type": "object", "description": "Error response returned by a Connect API operation.", "required": [ "error" ], "properties": { "error": { "type": "object", "description": "Error details.", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable error message." } }, "additionalProperties": true } } } ``` ### 500: An internal error occurred. Content-Type: `application/json` ```json { "type": "object", "description": "Error response returned by a Connect API operation.", "required": [ "error" ], "properties": { "error": { "type": "object", "description": "Error details.", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable error message." } }, "additionalProperties": true } } } ``` ### 502: A dependency returned an invalid or unsuccessful response. Content-Type: `application/json` ```json { "type": "object", "description": "Error response returned by a Connect API operation.", "required": [ "error" ], "properties": { "error": { "type": "object", "description": "Error details.", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable error message." } }, "additionalProperties": true } } } ``` --- ## Related - [connect endpoints](/docs/rest-api#connect) - [REST API overview](/docs/rest-api) - [OpenAPI spec](https://openapi.vercel.sh/) (machine-readable, all endpoints) --- [View full sitemap](/docs/sitemap)