---
title: "Create a connector"
method: POST
path: "/v1/connect/connectors"
tags: ["connect"]
---

# Create a connector

`POST /v1/connect/connectors`

Create a connector from type-specific configuration and optionally link it to a project during creation.

## Request body

- object
  - `data` union, required
    - object
      - `serverUrl` string
      - `serverConfig` object
        - `issuer` string
        - `authorization_endpoint` string
        - `token_endpoint` string
        - `userinfo_endpoint` string
        - `jwks_uri` string
        - `jwks` object
          - `keys` object[], required
            - `kty` string, required
            - `kid` string
            - `use` 'sig' | 'enc'
            - `key_ops` string[]
            - `alg` string
        - `revocation_endpoint` string
        - `introspection_endpoint` string
        - `end_session_endpoint` string
        - `device_authorization_endpoint` string
        - `registration_endpoint` string
        - `response_types_supported` string[]
        - `token_endpoint_auth_methods_supported` string[]
        - `token_endpoint_auth_signing_alg_values_supported` string[]
        - `scopes_supported` string[]
        - `grant_types_supported` string[]
        - `response_modes_supported` string[]
        - `subject_types_supported` string[]
        - `id_token_signing_alg_values_supported` string[]
        - `id_token_encryption_alg_values_supported` string[]
        - `id_token_encryption_enc_values_supported` string[]
        - `claim_types_supported` string[]
        - `claims_supported` string[]
        - `code_challenge_methods_supported` string[]
        - `prompt_values_supported` string[]
        - `claims_parameter_supported` boolean
        - `request_parameter_supported` boolean
        - `request_uri_parameter_supported` boolean
        - `require_request_uri_registration` boolean
        - `service_documentation` string
        - `op_policy_uri` string
        - `op_tos_uri` string
        - `logo_uri` string
        - `client_id_metadata_document_supported` boolean
        - `authorization_details_types_supported` string[]
      - `clientId` string, required
      - `clientName` string
      - `clientSecret` string
      - `tokenEndpointAuthMethod` string
      - `responseType` string
      - `pkceRequired` boolean
      - `codeChallengeMethod` string
      - `userAuthorization` object
        - `enabled` boolean, required
        - `scopes` string[] — Default scopes to request when token params specify scopes: [\"*\"].
      - `refreshTokens` object
        - `enabled` boolean, required
      - `clientCredentials` object
        - `enabled` boolean, required
        - `scopes` string[] — Default scopes to request when token params specify scopes: [\"*\"].
      - `forwardedClaims` object — Allow-list of extra claims to propagate, keyed by source (idToken). Only claims named here and present in that source are exposed.
        - `idToken` string[]
      - `defaultAudience` string
      - `defaultTokenExpiresIn` number — Default token lifetime in seconds to use when the token response omits expires_in.
      - `authorizationUrlParams` object
      - `jwtBearer` object
        - `enabled` boolean
        - `scopes` string[] — Default scopes to request when token params specify scopes: [\"*\"].
        - `sub` string
        - `iss` string
        - `aud` string
        - `additionalClaims` object
        - `ttl` number
        - `useClientCredentials` boolean
      - `clientAssertion` object
        - `type` string
        - `ttl` number
        - `claims` object
    - object
      - `subjectType` 'app' | 'user'
      - `values` object[]
        - `value` string, required
        - `scope` string
        - `expiresAt` integer — The timestamp when the API key value expires in milliseconds.
    - object
      - `appId` integer, required
      - `appSlug` string, required
      - `appName` string, required
      - `clientId` string, required
      - `owner` object
        - `type` 'user' | 'organization' | 'User' | 'Organization', required
        - `id` integer, required
        - `slug` string, required
        - `name` string
      - `clientSecret` string
      - `privateKeyPem` string
      - `webhookSecret` string
      - `extras` object
    - object
      - `appId` string
      - `appName` string
      - `clientId` string, required
      - `clientSecret` string, required
      - `webhookSecret` string
      - `appScopes` string[]
      - `userScopes` string[]
      - `ownerOrganization` object
        - `id` string, required
        - `slug` string, required
        - `name` string, required
        - `logoUrl` string, nullable
      - `application` object
        - `id` string, required
        - `clientId` string, required
        - `name` string, required
        - `description` string, nullable
        - `developer` string, nullable
        - `developerUrl` string, nullable
        - `imageUrl` string, nullable
        - `redirectUris` string[]
        - `distribution` string, nullable
        - `webhookResourceTypes` string[]
        - `webhookUrl` string, nullable
        - `webhookEnabled` boolean
        - `createdAt` string
        - `updatedAt` string
      - `extras` object
    - object
      - `consumerKey` string, required
      - `consumerSecret` string, required
      - `loginHost` string, required
    - object
      - `appId` string, required
      - `appName` string, required
      - `clientId` string, required
      - `clientSecret` string, required
      - `slackTeam` object
        - `id` string, required
        - `name` string
        - `domain` string
      - `signingSecret` string
      - `verificationToken` string
      - `botScopes` string[]
      - `userScopes` string[]
      - `extras` object
    - object
      - `clientName` string
      - `accountIdentifier` string, required
      - `defaultSessionRole` string
      - `extras` object
    - object
      - `clientName` string
      - `accountIdentifier` string
      - `extras` object
    - object
      - `projectId` string, required
      - `projectSecret` string, required
      - `webhookSecret` string
    - object
  - `icon` string
  - `backgroundColor` string
  - `accentColor` string
  - `type` string — Known types: api-key, github, linear, oauth, photon, salesforce, slack, snowflake. Optional when \"connectionMethod\" is set.
  - `service` string — Service slug or URL for which the connector is used.
  - `connectionMethod` string — Connection method slug of the service.
  - `params` object — Values for the connection method's templateFields.
  - `target` string — Which of the service's targets this connector is for. Requires \"connectionMethod\" and must be one that method serves. Optional.
  - `uid` string
  - `name` string
  - `projectId` string — Link to the specified project when specified. See environments.
  - `environments` union[] — Use these built-in environment names or stable custom environment IDs when linking to projectId.
    - union — A built-in environment name or the stable env_* ID of a custom environment.
      - string
      - string
  - `triggers` boolean — Whether the triggers are enabled for this connector.
  - `events` string[] — The list of the defaults trigger events for this connector.

## Response `201`

- object
  - `id` string, required
  - `ownerId` string, required
  - `createdAt` number, required
  - `updatedAt` number, required
  - `deletedAt` number
  - `reinstallAt` number — Time when this connector started requiring reinstallation because an installation-affecting app-token grant changed.
  - `createdBy` union
    - object — 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.
      - `type` 'user', required
      - `id` string, required
    - object — 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.
      - `type` 'project', required
      - `id` string, required
      - `environment` union, required
        - string
        - 'development' | 'preview' | 'production'
  - `updatedBy` union
    - object — 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.
      - `type` 'user', required
      - `id` string, required
    - object — 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.
      - `type` 'project', required
      - `id` string, required
      - `environment` union, required
        - string
        - 'development' | 'preview' | 'production'
  - `creationMode` 'managed' | 'manual' — How the connector row was originally created. New create paths stamp this explicitly; older rows may omit it.
  - `managed` object — Managed-client metadata exposed without leaking the manager client or installation identifiers.
    - `sync` false | true
  - `public` false | true, required
  - `uid` string, required
  - `type` 'api-key' | 'custom' | 'discord' | 'github' | 'linear' | 'microsoft-entra' | 'oauth' | 'photon' | 'salesforce' | 'slack' | 'snowflake' | 'snowflake-wif', required
  - `service` string, required — 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`.
  - `connectionMethod` string — The connection method this connector was created from, when the create request named one.
  - `target` string — Which of the service's products/surfaces this connector points at.
  - `name` string, required
  - `clientUrl` string, nullable
  - `redirectUri` string — 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` string
  - `data` object, required
  - `typeName` string, required
  - `typeIcon` string
  - `website` string
  - `devsite` string
  - `docsite` string
  - `icon` string — 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` string — Hex background color (e.g., `#000000`) for branding.
  - `accentColor` string — Hex accent color (e.g., `#000000`) for branding.
  - `supportedSubjectTypes` string[], required
  - `appTokens` object
    - `crossInstallation` false | true, required
    - `supportsRefinement` false | true, required
    - `requiresReinstallation` false | true — True when changing app token grants requires reinstalling the app, so tokens cannot be partitioned independently by requester environment.
    - `scopes` string[] — 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.
    - `supportedAuthorizationDetails` string[]
    - `permissionsUrl` string — Link to the page on the service where this client's app-level permissions are declared and granted, when the service has one and it differs from `clientUrl`.
  - `userTokens` object
    - `crossInstallation` false | true, required
    - `supportsRefinement` false | true, required
    - `scopes` string[] — Known allowed user-level scopes. For Slack this is the user scope set configured on the app; for OAuth it is `scopes_supported` from the server's discovery document.
    - `supportedAuthorizationDetails` string[]
    - `manualCredentialInput` false | true — User authorization is completed by the Connect consent screen submitting a credential instead of an OAuth redirect.
  - `supportsInstallation` false | true, required
  - `supportsRevocation` false | true, required
  - `ownerTenantId` string
  - `supportsTriggers` false | true, required — Whether this client type supports trigger webhooks. Derived from the type definition; indicates that `triggers` and `triggerDestinations` may be meaningful for this client.
  - `supportsIcon` unknown, required
  - `triggers` object — Incoming trigger configuration. Only present when enabled.
    - `enabled` false | true, required
  - `events` string[] — 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.
  - `triggerDestinations` object[] — Destinations that incoming triggers should be forwarded to. Limited to `MAX_CONNEX_TRIGGER_DESTINATIONS` entries.
    - `projectId` string, required
    - `customEnvironmentId` string — Stable custom-environment ID to route this destination to. Mutually exclusive with `branch`; omitted destinations keep the legacy production behavior.
    - `branch` string
    - `path` string
  - `isConnectedToPrioritizedProject` false | true — Whether this connector is linked to the project supplied through `prioritizedProjectId`. Only present on prioritized list responses.
  - `includes` object — Optional expansions populated by `?include=...` on the list endpoint.
    - `projects` object — Set by `?include=projects`. Capped at 100 per client.
      - `items` object[], required
        - `clientId` string, required
        - `projectId` string, required
        - `project` object
          - `id` string, required
          - `name` string, required
          - `customEnvironments` object[]
            - `id` string, required
            - `slug` string, required
        - `environments` union[], required
          - union
            - string
            - 'development' | 'preview' | 'production'
        - `createdAt` number, required
        - `updatedAt` number, required
      - `hasMore` false | true, required
      - `cursor` string, nullable

## Other responses

- `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`
- `409`
- `410`
- `422`
- `500`
- `502`

---

[API](https://skmtc.net/vercel/apis/api.md) · [All operations](https://skmtc.net/vercel/apis/api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/vercel/api/versions/61d1ba3f6dac/schema)