Quickstart

This guide shows you how to create your first connector in Vercel Connect and request a runtime provider token from your code.

• A Vercel account
• Vercel CLI installed (npm i -g vercel)
• Node.js 18 or later
• A Linear workspace you can authorize

1. Set up your environment

   Create a new directory and connect it to a Vercel project. Linking the directory to a project is the recommended way to authenticate, because the project handles secure OIDC token authentication for you.

   Terminal

   mkdir my-connect-app && cd my-connect-app
   pnpm init
   vercel link

   When prompted, select an existing project or Create a new project. The project doesn't need any code deployed; it just needs to exist so Vercel can issue OIDC tokens to it.

   Once linked, pull your environment variables to get a development OIDC token:

   Terminal

   vercel env pull

   This creates a .env.local file containing VERCEL_OIDC_TOKEN, which the SDK uses to authenticate calls to Vercel Connect. The token is short-lived; re-run vercel env pull if you see authentication errors. When you deploy to Vercel, token management happens automatically.

2. Create a Linear connector

   Create a connector for Linear so your code can mint Linear API tokens on behalf of a user. You can do this from the dashboard or the CLI.

   DashboardCLI

   Open Connect in the Vercel dashboard. You'll be prompted to pick a team and project; any connector you create from this page is automatically linked to that project, so you can skip a separate attach step.

   Select Create Connector, choose OAuth, and keep Managed selected. Under Server URL, enter mcp.linear.app, select Continue, and set Connector Name to linear.

   Creating the connector from this project page automatically links Production, Preview, and Development. To enable a Custom Environment, create the connector first, then open its Projects section, edit the project link, and select the Custom Environment.

   Create the connector. Vercel opens your browser to complete the Linear OAuth flow:

   Terminal

   vercel connect create mcp.linear.app --name linear

   For a known service such as notion or okta, the CLI prompts you for the connection method and any credentials it needs, so you can finish setup without leaving the terminal. Run vercel connect create <service> --help to see what a service supports.

   Attach the connector to the currently linked project so it can request tokens:

   Terminal

   vercel connect attach oauth/linear

   By default, attach links Production, Preview, and Development. It does not automatically include Custom Environments. Use -e production -e preview to restrict the link, or pass a Custom Environment slug such as -e qa. See the vercel connect reference for the full surface.

   For provider-level isolation, create a separate connector for each environment, install each connector separately, and request only the provider scopes that environment needs. Environment selection on a project link controls which deployments can request tokens; it does not create separate provider grants.

3. Install the SDK

   Install @vercel/connect along with the dev dependencies you need to run a TypeScript script locally.

   npmyarnpnpmbun

   Terminal

   npm install @vercel/connect dotenv @types/node tsx typescript

   Terminal

   yarn add @vercel/connect dotenv @types/node tsx typescript

   Terminal

   pnpm add @vercel/connect dotenv @types/node tsx typescript

   Terminal

   bun add @vercel/connect dotenv @types/node tsx typescript

   dotenv loads .env.local so the SDK can read VERCEL_OIDC_TOKEN. The tsx package is a TypeScript runner, and typescript and @types/node provide the compiler and Node.js type definitions.

4. Write your code

   Create a file that requests a Linear token on behalf of a specific user and inspects the response:

   index.ts

   import { config } from 'dotenv';
   config({ path: '.env.local' });
    
   import {
     getTokenResponse,
     UserAuthorizationRequiredError,
   } from '@vercel/connect';
    
   const userId = 'user_demo_123';
    
   async function main() {
     try {
       const response = await getTokenResponse('oauth/linear', {
         subject: { type: 'user', id: userId },
         scopes: ['read'],
       });
    
       console.log(`Got token for ${userId} on ${response.connector.uid}`);
       console.log(`Expires at: ${new Date(response.expiresAt).toISOString()}`);
     } catch (error) {
       if (error instanceof UserAuthorizationRequiredError) {
         console.log(`User ${userId} has not authorized Linear yet.`);
         console.log('In a real app, surface the consent URL to the user here.');
         return;
       }
       throw error;
     }
   }
    
   main().catch(console.error);

   This requests a user-subject token: Vercel Connect will mint a Linear token that acts as user_demo_123, scoped to read. In a real app, replace user_demo_123 with the id you use to identify the signed-in user in your own database.

   For service-level operations (a bot account or a tenant-wide admin API), use subject: { type: 'app' } instead. App-subject tokens skip the user-consent flow entirely, though some providers still require a one-time installation or an administrator grant. For multi-tenant connector types like Slack or GitHub, pass installationId to address a specific workspace or organization; otherwise the connector's default installation is used. See Tokens for the full set of scoping options.

   Completing the consent flow

   When you catch UserAuthorizationRequiredError, call startAuthorization to get a consent URL to redirect the user to. After they authorize, Vercel completes the OAuth handshake server-side, and your next getToken call for that user succeeds.

   consent.ts

   import { startAuthorization } from '@vercel/connect';
    
   const { url } = await startAuthorization('oauth/linear', {
     subject: { type: 'user', id: userId },
     scopes: ['read'],
   });
    
   // In a web app, redirect the user to `url`.
   console.log(`Send the user to: ${url}`);

   Do not persist runtime tokens in long-lived environment variables. Call getToken (or getTokenResponse) at request time; the SDK keeps an in-process cache and refreshes the token automatically as it approaches expiry.

5. Run it

   Terminal

   pnpm tsx index.ts

   The first time you run this with a new userId, you'll see:

   Terminal

   User user_demo_123 has not authorized Linear yet.
   In a real app, surface the consent URL to the user here.

   That's because no Linear OAuth grant exists yet for user_demo_123. In a real app you'd catch UserAuthorizationRequiredError, redirect the user to the connector's consent URL, and retry the request once they authorize. Once the user has consented (try it from the connector's page in the dashboard for this demo), re-run the script and you'll see:

   Terminal

   Got token for user_demo_123 on oauth/linear
   Expires at: 2026-06-03T22:42:00.000Z

   If you need the token as a string for use in an Authorization header, use getToken instead of getTokenResponse.

1. Set up authentication: Linked a directory to a Vercel project and pulled an OIDC token so the SDK can authenticate with Vercel Connect.
2. Created a connector: Registered Linear as a Custom OAuth connector under your team and attached it to the project.
3. Requested a user-scoped token: Called getTokenResponse with a user subject to mint a short-lived Linear token that acts as a specific user, and handled the first-run consent case with UserAuthorizationRequiredError.

• Concepts: Understand connectors, installations, tokens, project links, triggers, and authentication.
• SDK Reference: Full getToken and getTokenResponse parameter reference.
• CLI Reference: The full vercel connect command surface.
• Pricing: Token-request pricing.
• Limits: Platform limits and rate limits.