Connector installations in Vercel Connect

A single connector represents your integration with a provider. An installation represents a single tenant within that integration, where a tenant is an account on the provider's side: one Slack workspace, one GitHub organization, one Microsoft Entra directory, one Salesforce org. One connector can have many installations, each with its own authorization grant.

Not every connector type supports installations. Snowflake, Salesforce, API Key, and Custom OAuth connectors reach exactly one account, so there's nothing to install and no installationId to pass. Slack, GitHub, and Linear can each serve any number of tenants: one Slack connector can hold an installation for every workspace your app is added to. For Microsoft, an installation is a tenant that granted the connector's Entra app admin consent.

Updating a connector's permissions doesn't change tokens already granted. New delegated scopes reach a user only after they authorize again. New application permissions need a fresh installation.

A user installs a connector by running an install flow specific to the provider. For Slack, that's the standard Slack workspace install. For GitHub, it's a GitHub app installation. For Microsoft, it's tenant-wide admin consent from a tenant administrator. The flow ends with the user redirected back to your application, and Vercel Connect records the installation against the connector.

Each installation has a stable installationId that you pass to getToken to scope a token request to that tenant:

import { getToken } from '@vercel/connect';
 
const token = await getToken('slack/acme-slack', {
  subject: { type: 'app' },
  installationId: 'inst_workspace_xyz',
  scopes: ['chat:write'],
});

If you omit installationId, Vercel Connect uses the default installation for the connector (when the type supports a default). If no default is set, the token request fails with ConnectorInstallationRequiredError.

For connector types that support it, pass installationId: '*' to request a token that's valid across all installations of the connector. This is useful for service-level operations that aren't bound to a single tenant, like listing webhooks across every workspace your app is installed in.

Cross-installation tokens are subject to the connector's capability matrix. Most provider APIs scope credentials to a single tenant, so '*' only works where the provider exposes a tenant-spanning credential.

Installations are added when a user completes the install flow and removed when a user uninstalls (from the provider side) or when an admin deletes the installation in the Vercel dashboard. Removing an installation revokes its tokens.

If your code calls getToken for a connector type that requires an installation but no installation exists (or the requested installationId doesn't match), the SDK throws ConnectorInstallationRequiredError. Treat this as a recoverable user-facing state: surface a "connect your workspace" UI rather than a 500.

• Connectors: The parent record that an installation belongs to.
• Tokens: How a token request is scoped (subject, installation, scopes, resources).
• SDK Reference: getToken parameters and errors.