--- title: get-a-connector product: vercel url: /docs/rest-api/connect/get-a-connector canonical_url: "https://vercel.com/docs/rest-api/connect/get-a-connector" last_updated: 2026-09-02 type: reference prerequisites: [] related: - /docs/rest-api summary: Learn about get-a-connector on Vercel. install_vercel_plugin: npx plugins add vercel/vercel-plugin --- # Get a connector ```http GET /v1/connect/connectors/{connector} ``` Get the connector by ID. Accepts a dashboard/team requester or a deployment's project OIDC token; project requesters may only read connectors linked to their project and environment. ## Authentication **bearerToken**: HTTP bearer ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `connector` | string | Yes | Stable connector ID or URL-encoded team-scoped UID. Examples: `scl_abc123` or `slack%2Fmy-bot`. | ## 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. | ## Example request ### TypeScript ```typescript const response = await fetch('https://api.vercel.com/v1/connect/connectors/connector?teamId=string&slug=string', { method: 'GET', headers: { 'Authorization': 'Bearer YOUR_ACCESS_TOKEN', 'Content-Type': 'application/json', }, }); 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/connector?teamId=string&slug=string', { method: 'GET', headers: { 'Authorization': `Bearer ${process.env.VERCEL_ACCESS_TOKEN}`, 'Content-Type': 'application/json', }, next: { revalidate: 3600 } }); if (!response.ok) { throw new Error('Request failed'); } return response.json(); } ``` ### cURL ```bash curl -X GET 'https://api.vercel.com/v1/connect/connectors/connector?teamId=string&slug=string' \ -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ -H 'Content-Type: application/json' ``` ## 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 ### 200: The connector. Content-Type: `application/json` ```json { "type": "object", "description": "A connector that defines how Vercel accesses an external service.", "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 query 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 } } } ``` ### 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 } } } ``` --- ## 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)