--- 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-06-08 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 from type-specific configuration and optionally link it to a project during creation. ## Authentication **bearerToken**: HTTP bearer ## Request body Required: No Content-Type: `application/json` ```json { "type": "object", "required": [ "type", "data" ], "properties": { "type": { "type": "string", "description": "Known types: api-key, github, oauth, salesforce, slack, snowflake." }, "service": { "type": "string", "description": "Service slug or URL for which the connector is used." }, "uid": { "type": "string" }, "name": { "type": "string" }, "projectId": { "type": "string", "description": "Link to the specified project when specified. See environments." }, "environments": { "type": "array", "description": "Use these environments when linking to the project specified by the projectId.", "items": { "type": "string" } }, "triggers": { "type": "boolean", "description": "Whether the triggers are enabled for this connector." }, "events": { "type": "array", "description": "The list of the defaults trigger events for this connector.", "items": { "type": "string" } }, "icon": { "type": "string", "description": "Branding icon. Either a SHA-1 hash already uploaded to the Vercel avatar service or an https:// URL that will be downloaded and rehosted." }, "backgroundColor": { "type": "string", "description": "Branding background color (6-digit hex, e.g. \"#000000\").", "pattern": "^#[0-9a-fA-F]{6}$" }, "accentColor": { "type": "string", "description": "Branding accent color (6-digit hex, e.g. \"#000000\").", "pattern": "^#[0-9a-fA-F]{6}$" }, "data": { "anyOf": [ { "type": "object", "required": [ "clientId" ], "properties": { "serverUrl": { "type": "string" }, "serverConfig": { "type": "object", "default": {} }, "clientId": { "type": "string" }, "clientSecret": { "type": "string" }, "tokenEndpointAuthMethod": { "type": "string", "default": "client_secret_post" }, "responseType": { "type": "string" }, "pkceRequired": { "type": "boolean" }, "codeChallengeMethod": { "type": "string" }, "userAuthorization": { "type": "object", "required": [ "enabled" ] }, "refreshTokens": { "type": "object", "required": [ "enabled" ] }, "clientCredentials": { "type": "object", "required": [ "enabled" ] }, "defaultAudience": { "type": "string" }, "authorizationUrlParams": { "type": "object" }, "jwtBearer": { "type": "object" } } }, { "type": "object", "required": [ "values" ], "properties": { "values": { "type": "array" } } }, { "type": "object", "required": [ "appId", "appSlug", "appName", "clientId" ], "properties": { "appId": { "type": "integer" }, "appSlug": { "type": "string" }, "appName": { "type": "string" }, "clientId": { "type": "string" }, "owner": { "type": "object", "required": [ "type", "id", "slug" ] }, "clientSecret": { "type": "string" }, "privateKeyPem": { "type": "string" }, "webhookSecret": { "type": "string" }, "extras": { "type": "object" } } }, { "type": "object", "required": [ "consumerKey", "consumerSecret", "loginHost" ], "properties": { "consumerKey": { "type": "string" }, "consumerSecret": { "type": "string" }, "loginHost": { "type": "string" } } }, { "type": "object", "required": [ "appId", "appName", "clientId", "clientSecret" ], "properties": { "appId": { "type": "string" }, "appName": { "type": "string" }, "clientId": { "type": "string" }, "clientSecret": { "type": "string" }, "slackTeam": { "type": "object", "required": [ "id" ] }, "signingSecret": { "type": "string" }, "verificationToken": { "type": "string" }, "botScopes": { "type": "array" }, "userScopes": { "type": "array" }, "extras": { "type": "object" } } }, { "description": "(2 more variants — see OpenAPI spec)" } ] } } } ``` ## Responses ### 201: No description Content-Type: `application/json` ```json { "type": "object", "required": [ "createdAt", "data", "id", "name", "ownerId", "public", "service", "supportedSubjectTypes", "supportsIcon", "supportsInstallation", "supportsRevocation", "supportsTriggers", "type", "typeName", "uid", "updatedAt" ], "properties": { "id": { "type": "string" }, "ownerId": { "type": "string" }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "deletedAt": { "type": "number" }, "createdBy": { "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", "enum": [ "user" ] }, "id": { "type": "string" } } }, { "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", "enum": [ "project" ] }, "id": { "type": "string" }, "environment": { "type": "string", "enum": [ "development", "preview", "production" ] } } } ] }, "updatedBy": { "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", "enum": [ "user" ] }, "id": { "type": "string" } } }, { "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", "enum": [ "project" ] }, "id": { "type": "string" }, "environment": { "type": "string", "enum": [ "development", "preview", "production" ] } } } ] }, "public": { "type": "boolean", "enum": [ false, true ] }, "uid": { "type": "string" }, "type": { "type": "string", "enum": [ "api-key", "custom", "github", "oauth", "salesforce", "slack", "snowflake" ] }, "service": { "type": "string", "description": "Best-effort identifier of the third-party service this client represents, independent of `type`. Examples: `'slack'`, `'mcp.linear.app'`, `'auth.example.com'`. Always non-empty on the API response — falls back through `storedClient.service ?? typeDef.service ?? typeDef.type`." }, "name": { "type": "string" }, "clientUrl": { "type": "string", "nullable": true }, "redirectUri": { "type": "string", "description": "Redirect URI registered with the third-party service for this client, if any. Used by `startAuthorization`/`startInstallation` to replay the exact URI back to the provider's token endpoint. Absent on clients created before this field was introduced; those callers fall back to the `https://connect.vercel.com/callback` default." }, "defaultInstallationId": { "type": "string" }, "data": { "type": "object", "additionalProperties": true }, "typeName": { "type": "string" }, "typeIcon": { "type": "string" }, "website": { "type": "string" }, "devsite": { "type": "string" }, "docsite": { "type": "string" }, "icon": { "type": "string", "description": "Client branding icon. SHA-1 hash that resolves to the uploaded icon via the Vercel avatar service. Clients 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", "items": { "type": "string" } }, "appTokens": { "type": "object", "required": [ "crossInstallation", "supportsRefinement" ], "properties": { "crossInstallation": { "type": "boolean", "enum": [ false, true ] }, "supportsRefinement": { "type": "boolean", "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 `scopes_supported` from the server's discovery document.", "items": { "type": "string" } }, "supportedAuthorizationDetails": { "type": "array", "items": { "type": "string" } } } }, "userTokens": { "type": "object", "required": [ "crossInstallation", "supportsRefinement" ], "properties": { "crossInstallation": { "type": "boolean", "enum": [ false, true ] }, "supportsRefinement": { "type": "boolean", "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 `scopes_supported` from the server's discovery document.", "items": { "type": "string" } }, "supportedAuthorizationDetails": { "type": "array", "items": { "type": "string" } } } }, "supportsInstallation": { "type": "boolean", "enum": [ false, true ] }, "supportsRevocation": { "type": "boolean", "enum": [ false, true ] }, "ownerTenantId": { "type": "string" }, "supportsTriggers": { "type": "boolean", "description": "Whether this client type supports trigger webhooks. Derived from the type definition; indicates that `triggers` and `triggerDestinations` may be meaningful for this client.", "enum": [ false, true ] }, "supportsIcon": { "enum": [ false, "maybe", true ] }, "triggers": { "type": "object", "description": "Incoming trigger configuration. Only present when enabled.", "required": [ "enabled" ], "properties": { "enabled": { "type": "boolean", "enum": [ false, true ] } } }, "events": { "type": "array", "description": "Known events this client 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 `MAX_CONNEX_TRIGGER_DESTINATIONS` entries.", "items": { "type": "object", "description": "Destinations that incoming triggers should be forwarded to. Limited to `MAX_CONNEX_TRIGGER_DESTINATIONS` entries.", "required": [ "projectId" ], "properties": { "projectId": { "type": "string" }, "branch": { "type": "string" }, "path": { "type": "string" } } } }, "includes": { "type": "object", "description": "Optional expansions populated by `?include=...` on the list endpoint.", "properties": { "projects": { "type": "object", "description": "Set by `?include=projects`. Capped at 100 per client.", "required": [ "hasMore", "items" ], "properties": { "items": { "type": "array" }, "hasMore": { "type": "boolean", "enum": [ false, true ] }, "cursor": { "type": "string", "nullable": true } } } } } } } ``` ### 400: One of the provided values in the request body is invalid. ### 401: The request is not authorized. ### 403: You do not have permission to access this resource. ### 404: No description ### 409: No description --- ## 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)