The Complete Guide to Vercel Connect

Agents and background services often need to call provider APIs such as Slack, GitHub, Microsoft, or Snowflake on behalf of your users. Doing so usually means storing long-lived provider secrets in your database or environment variables.

Vercel Connect keeps those secrets out of your runtime by issuing short-lived tokens on demand, scoped to the projects and environments that need them. You register a connector once at the team level, link it to a project, then request a token at runtime when your code calls the provider.

This guide covers the full product, from the conceptual model through a working Slack integration you build along the way.

Copy link to headingOverview

In this guide, you'll learn how to:

• Understand the five core concepts behind Vercel Connect
• Create a connector and link it to a project, including Custom Environments
• Request runtime tokens with getToken, and scope them with subjects, installations, scopes, and resources
• Handle token caching, refresh, revocation, and the SDK's typed errors
• Forward and verify provider webhooks with triggers
• Monitor token requests, authorizations, and trigger deliveries with Observability
• Understand pricing for token requests and triggers

Copy link to headingPrerequisites

Before you begin, make sure you have:

• A Vercel account
• Permission to create connectors and link them to projects
• A Slack workspace where you can install apps

For local development, you also need Node.js 24+, pnpm, and the Vercel CLI.

Copy link to headingHow Vercel Connect works

Vercel Connect is built around a connector, a team-owned record that represents one third-party service and that your whole team can reuse.

You link a connector to the projects that need it, and your code requests a token from that connector at runtime instead of reading a stored secret. Vercel records each authorization, token request, and trigger delivery, so you keep an audit trail of how external access is used.

Connect uses five main concepts:

Tokens are the outbound half of Vercel Connect (your code calling the provider), and triggers are the inbound half (the provider calling your code).

Copy link to headingConnector identifiers

Each connector has four identifiers:

• uid: The stable, human-readable string you set, such as slack/acme-slack. When you call getToken('slack/acme-slack'), that string is the uid.
• id: An opaque internal identifier that Vercel Connect uses in API responses.
• service: The third-party service the connector reaches, such as slack. Custom OAuth connectors instead identify the service by its URL.
• type: How Vercel Connect authenticates to that service, such as slack, github, microsoft-entra, oauth, or api-key.

Copy link to headingToken subject types

Each token request specifies the subject it represents. One connector can issue tokens for any of three subjects:

For jwt-bearer, you can pass optional iss and aud claims to override the connector's OAuth client ID and token endpoint, and additionalClaims to carry any extra fields the provider requires.

Copy link to headingConnector ownership models

Connectors fall into two operating models, based on who registers the OAuth client (or credential) with the provider.

With a Vercel Managed Connector, Vercel registers the OAuth client, and you authorize it against your account or workspace, so you never register an OAuth client or manage client secrets:

For any other service, create a Customer Managed Connector. Bring your own client ID and secret with Custom OAuth (OAuth 2.0 or OIDC, supporting the authorization-code flow with PKCE and the client-credentials flow), or supply a long-lived API key at creation time. Use the authorization-code flow for user subjects and the client-credentials flow for app subjects.

Vercel already knows how to connect to many services. When you create a connector for a known service, Vercel fills in the authorization and token endpoints and the provider's default scopes, so you only supply what's specific to your account. For providers that support automatic client registration, Vercel Assisted Setup creates the OAuth client for you. You can also enter a server URL, such as mcp.linear.app, and Vercel reads the provider's published OAuth metadata to fill in the endpoints.

Browse the connector catalog for the current services and connection methods. Each connector page includes authentication options, trigger support, and setup instructions.

Copy link to headingHow authentication works

Every token request has two legs that both have to authenticate: your code calling Vercel Connect, and Vercel Connect calling the provider.

For the first leg, the @vercel/connect SDK supports two methods:

On Vercel, the SDK reads the OIDC token that Vercel injects into your deployment automatically. Connect verifies the token's claims against the connector's project links to confirm the calling project and environment are allowed to request tokens.

For local development, run vercel link followed by vercel env pull to download a development token into .env.local. The token expires after about 12 hours, so re-run vercel env pull if you see authentication errors.

For external CI/CD or non-Vercel environments, pass a Vercel access token through the vercelToken option.

One important difference between the two: an access token can only request subjects it represents ({ type: 'app' }, or its own user). Requesting a user token for a different user requires an OIDC token, which represents the project rather than any single user.

For the second leg, Vercel Connect drives the provider's own flow, whether that's the app install for Slack, GitHub, and Linear, admin consent for Microsoft Entra, or the full OAuth authorization-code flow with automatic refresh for OAuth-based connectors. The refresh token is stored on Vercel's infrastructure, and your code never sees it. You only ever receive short-lived access tokens through getToken.

Copy link to headingCreate a connector

You can create a connector from the dashboard or the Vercel CLI.

In the dashboard, open the Connect page in your team, select Create Connector, and choose Slack as the type. Name the connector (for example, acme-slack).

To do the same in the terminal, run:

vercel connect create slack --name acme-slack

For a known service, the CLI prompts you for the product, the connection method, and the credentials that method needs, and opens your browser only when the provider requires you to sign in or install an app.

Run vercel connect create <service> --help to see what a service supports.

You can also create connectors for other services by name or by URL:

vercel connect create github --name acme-github
vercel connect create mcp.linear.app --name linear-connector

The connector has no time-to-live: unless you delete it, it lives indefinitely. Deletion is soft by default; a deleted connector cannot serve new token requests, and you can permanently remove it with vercel connect remove --disconnect-all.

Copy link to headingLink the connector to a project

Project link connects a team-owned connector to a Vercel project on the same team and records the environments from which that project can request tokens. The link is what authorizes a runtime token request: when your deployment calls getToken, the Vercel Connect API checks the calling project's OIDC token against the connector's project links. If no link exists for the calling project, or the link doesn't include the calling environment, the API rejects the request.

In the dashboard:

1. From the Vercel Dashboard, open Connect for your team.
2. Select the connector you want to use.
3. Under Projects, add a project or edit an existing project.
4. Select each environment that can request tokens.
5. Select Connect for a new project or Save when editing.

From the CLI, run vercel connect attach from a directory linked to a Vercel project, or pass --project to select one. Pass a built-in environment name or Custom Environment slug to --environment:

vercel connect attach slack/acme-slack --project my-project --environment qa

Repeat --environment, or provide a comma-separated list, to enable more than one environment. If you omit the option, the CLI links production, preview, and development. It does not automatically include Custom Environments.

Removing a link with vercel connect detach or from the dashboard does not delete the connector or any installations. It only revokes the project's ability to request tokens.

Project links restrict which deployment environments can request tokens from a connector. They do not add restrictions to a provider token after it is issued, and environments on the same connector can use the same provider installation. For provider-level isolation, create a separate connector for each environment, install each connector separately, and request the narrowest scopes each integration needs.

Copy link to headingRequest a runtime token

Install the SDK:

pnpm add @vercel/connect

Scope each token request to the workload:

• Set provider scopes only for the action you need, or pass ['*'] to request the connector's default scopes for the selected subject type.
• Add installationId when you need to target a specific installation.
• With the SDK, you can also pass provider-specific resources (resource indicators that narrow the token to one channel, repo, or record set), authorizationDetails (rich authorization requests), and audience.

Request the token from your server-side code with getToken and use it in an Authorization header:

import { getToken } from '@vercel/connect';

const token = await getToken('slack/acme-slack', {
  subject: { type: 'app' },
  scopes: ['chat:write'],
});

await fetch('https://slack.com/api/chat.postMessage', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ channel: 'C123', text: 'hello' }),
});

To request the same app token from the Vercel CLI:

vercel connect token slack/acme-slack --subject app --scopes chat:write

The CLI supports --subject, --installation-id, and --scopes. resources and authorizationDetails are SDK-only.

Your code now receives a runtime token scoped to the requested action. Request tokens at runtime, and don't persist them in long-lived environments.

Copy link to headingTarget an installation

An installation represents a single tenant within a connector, such as one Slack workspace, one GitHub organization, or one Microsoft Entra directory. Slack, GitHub, and Linear connectors can each serve any number of tenants, while Snowflake, Salesforce, API key, and Custom OAuth connectors reach exactly one account, so there's nothing to install and no installationId to pass.

You usually don't need to set installationId. When you omit it, Vercel Connect uses the connector's default installation, which covers the predominant case of a private app installed in a single workspace.

Pass a stable installationId explicitly when the connector spans more than one installation and you need to target a specific tenant:

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

For connector types that support it, pass installationId: '*' to request a cross-installation 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. Most provider APIs scope credentials to a single tenant, so '*' only works where the provider exposes a tenant-spanning credential.

Copy link to headingInspect the token response

If you need the token's expiry, the installation it was issued against, the provider's tenant ID, or other provider metadata, call getTokenResponse:

import { getTokenResponse } from '@vercel/connect';

const response = await getTokenResponse('slack/acme-slack', {
  subject: { type: 'app' },
});

console.log(response.connector.uid);
console.log(response.tenantId);
console.log(new Date(response.expiresAt).toISOString());

When you need connector setup values beyond a runtime token, such as a Snowflake account identifier, call getConnectorMetadata. It returns the connector's public metadata and provider-specific configuration under vendor.

Copy link to headingCaching and refresh

The SDK keeps an in-process LRU cache of up to 100 entries, keyed by the connector and request parameters. A cached token is reused on subsequent calls until it falls within the validityBufferMs window, 30 seconds by default and overridable per call. When that happens, the next call fetches a fresh one.

Vercel Connect automatically drives the provider's refresh flow, so your code never refreshes tokens itself. You can call getToken on each request without minting a new token every time.

Two escape hatches cover the cases where the cache gets in your way.

Pass { forceRefresh: true } as the third argument to bypass the cache and revalidate the grant. If a provider rejects a cached token with a 401, call deleteTokenCacheEntry with the same connector and parameters instead, and the next request fetches a fresh token:

import { deleteTokenCacheEntry, getToken } from '@vercel/connect';

const params = {
  subject: { type: 'app' as const },
  scopes: ['chat:write'],
};

let token = await getToken('slack/acme-slack', params);

// If Slack rejects this token with a 401:
deleteTokenCacheEntry('slack/acme-slack', params);
token = await getToken('slack/acme-slack', params);

Copy link to headingRevocation

Revoking a token tells the provider to invalidate it at the source. You can revoke from the dashboard, through the REST API, from the CLI with vercel connect token revoke, or with the SDK's revokeToken function:

import { revokeToken } from '@vercel/connect';

await revokeToken('oauth/linear', {
  subject: { type: 'user', id: 'user_123' },
});

revokeToken revokes the provider grant for a connector subject and clears the SDK's in-process token cache.

Whether revocation actually invalidates the token depends on the provider:

• If the provider exposes a revocation endpoint, Vercel Connect calls it.
• If not, Vercel Connect marks the token for deletion in its own store, but the underlying provider credential may continue to work until it expires naturally.

Copy link to headingHandle token errors

The SDK throws typed error classes you can match on with instanceof. Treat most of them as recoverable user-facing states rather than 500s:

Copy link to headingForward webhooks with triggers

Triggers are incoming webhooks from third-party services that Vercel Connect verifies and forwards to your projects. The provider sends the webhook to Vercel Connect's intake endpoint. Vercel Connect verifies the request signature against the connector's signing key, rejects unsigned or invalid requests, then forwards the verified event to each registered trigger destination.

Trigger destinations combine a project, target, and path. The target can be Production, a Preview branch, or a Custom Environment. Connectors can have up to three trigger destinations, and forwarding is strictly opt-in: Vercel Connect delivers events only to the destinations you configure. Browse the connector catalog to see which services support triggers and their default events.

Register a destination when attaching a connector by passing --triggers:

vercel connect attach slack/acme-slack --project my-project --environment production --triggers

To target a Preview branch or set a custom receiver path, add --trigger-branch, --trigger-path, or both:

vercel connect attach slack/acme-slack --project my-project --environment production \
  --triggers --trigger-branch staging --trigger-path /api/slack-events

To target a Custom Environment, pass its slug to --trigger-environment:

vercel connect attach slack/acme-slack --project my-project --environment qa \
  --triggers --trigger-environment qa --trigger-path /api/slack-events

When registering destinations from the CLI:

• --trigger-environment and --trigger-branch are mutually exclusive and only valid with --triggers. If you omit both, the destination targets Production.
• If you omit --trigger-path, Vercel derives the receiver path from the connector and project framework.
• Before using a Custom Environment as a destination, deploy to it and assign a verified domain that serves the environment's latest deployment directly. Vercel Connect forwards events through that domain.

Copy link to headingHow destinations affect the project link

Registering a trigger destination also enables its target environment on the connector's project link, so deployments there can request tokens. The reverse doesn't hold: removing a destination does not remove its environment from the link. Edit the project link separately if you also want to revoke token access.

Copy link to headingVerify forwarded requests

Vercel Connect signs each request it forwards and publishes a signing key for each connector. Verify the signature in your handler before acting on the payload.

Copy link to headingDelivery failures and retries

Delivery fails if the target doesn't resolve to a deployment or your handler returns a 5xx status. Requests that receive status 500, 502, 503, or 504 are attempted up to three times. The dashboard shows aggregate trigger metrics rather than a per-event delivery log, so use the target deployment's runtime logs to investigate an individual request.

Copy link to headingMonitor connectors with Observability

Every connector has an Observability tab that shows runtime events for token and trigger lifecycles: who requested a token, which project used it, when a trigger arrived, and where it was forwarded. Observability is available on all plans, and Enterprise teams also get connector audit logs and longer event retention.

The tab shows five event types: Token Request, Completed Authorization Request, Revoked Token Request, Inbound Trigger, and Forward Trigger. You can filter the list by event type, delivery status, environment, project ID, subject type, installation ID, and a time range that adapts to your plan's retention window.

Each event carries stable correlation IDs you can use to trace a single token or trigger across events and match Connect events to your own systems:

• tokenId: Identifies a specific issued token.
• authorizationId: Links to the OAuth authorization that produced the token.
• tokenGroupId: Groups tokens that share the same authorization context.
• triggerRequestId: Correlates an inbound trigger with its forwarded deliveries.

Event retention depends on your plan:

To retain events beyond your plan's retention window, add a Drain, available on Pro and Enterprise plans. Drains deliver each event as a JSON webhook payload to any HTTP endpoint. Use them to store events in your logging or SIEM system, build dashboards and alerts around token activity, or meet compliance requirements. Each drained event follows the schema in the events reference.

Copy link to headingBest practices

• Use a separate connector per environment when you need provider-level isolation. The project link controls which deployments can request tokens, but environments on the same connector can reach the same provider installations. Giving each environment its own connector ensures each has its own authorization grant, scopes, and audit trail.
• Request the minimum required scopes. Pass scopes, resources, or authorizationDetails to narrow what a token can do, rather than requesting a tenant-wide token when you need to read one channel.
• Keep tokens out of storage. Request tokens at runtime and avoid persisting them in long-lived environment variables or a database.
• Prefer OIDC over access tokens. OIDC tokens are short-lived, project-bound, and rotated automatically. Reserve vercelToken for environments where OIDC isn't an option, such as non-Vercel platforms.
• Refresh vercel env pull regularly during local development. The development OIDC token expires after about 12 hours, so pull a fresh token if getToken starts failing with auth errors after a long break.

Copy link to headingPricing

Vercel Connect is billed by token requests and triggers. Token requests are single calls to the Vercel Connect API that return a provider token, while triggers are incoming webhooks that Vercel Connect verifies and forwards.

In-process token caching reduces token requests: the SDK reuses a cached token across calls until it falls inside the validity buffer, so a typical agent that makes many provider calls in one invocation pays for one token request, not many.

Each trigger destination that receives a webhook event counts as one trigger, so an event forwarded to three destinations counts as three triggers. If no trigger destinations are configured, each incoming webhook event still counts as one trigger. To stop trigger billing entirely, remove the webhook URL from the provider's dashboard so the provider stops sending events to Vercel Connect. Triggers are only counted for connectors that support trigger forwarding.

Copy link to headingLimits

Copy link to headingWhen to use Vercel Connect or Integrations

Use Vercel Connect when you need delegated runtime credentials, when the same provider serves multiple Vercel projects or environments, or when an agent needs to act on behalf of a user. Common examples include running an agent that needs project-scoped access to a Slack workspace, linking a single connector to multiple projects and environments, or requesting short-lived provider tokens at runtime instead of storing long-lived secrets.

Use Vercel Integrations instead when you want a marketplace-managed install for a provider-billed product in the Vercel Marketplace.

Copy link to headingRelated resources and next steps

• Follow the Vercel Connect quickstart for the first-setup walkthrough.
• See the SDK Reference for getToken, getTokenResponse, getConnectorMetadata, revokeToken, and the full types.
• See the Vercel Connect CLI reference for every subcommand and option.