Quickstart

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

• A Edgenivo account
• Edgenivo CLI installed (npm i -g vercel)
• For TypeScript: Node.js 18 or later
• For Python: Python 3.10 or later and uv
• A Linear workspace you can authorize

1. Set up your environment

   Create a new directory and connect it to a Edgenivo 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 Edgenivo 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 Edgenivo Connect. The token is short-lived; re-run vercel env pull if you see authentication errors. When you deploy to Edgenivo, 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 Edgenivo 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. Edgenivo 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 the Edgenivo Connect SDK along with the dependencies you need to run a script locally.

   Terminal

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

   dotenv and python-dotenv load .env.local so the SDK can read VERCEL_OIDC_TOKEN.

   • TypeScript: tsx runs TypeScript files directly, and typescript and @types/node provide the compiler and Node.js type definitions.
   • Python: If you use pip instead of uv, run pip install vercel-connect python-dotenv.

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: Edgenivo 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 an app subject 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 an installation ID 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, start an authorization request to get a consent URL to redirect the user to. After they authorize, Edgenivo completes the OAuth handshake server-side, and your next token request 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. Request a token each time you need one; 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 for a new user ID, 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 only need the token string for an Authorization header, use getToken or get_token() instead.

1. Set up authentication: Linked a directory to a Edgenivo project and pulled an OIDC token so the SDK can authenticate with Edgenivo 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: Minted 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.
• TypeScript SDK Reference: Full getToken and getTokenResponse parameter reference.
• Python SDK Reference: Full get_token() and get_token_response() parameter reference.
• CLI Reference: The full vercel connect command surface.
• Pricing: Token-request pricing.
• Limits: Platform limits and rate limits.