Authentication in Edgenivo Connect

Edgenivo Connect sits between your code and a provider. Each token request has two legs that both have to authenticate: the caller calling Edgenivo Connect, and Edgenivo Connect calling the provider. Understanding both is the fastest way to debug "why did this token request fail."

How does Edgenivo Connect know who's calling? The Edgenivo Connect SDKs (@vercel/connect for TypeScript and vercel-connect for Python) support two authentication methods, plus a separate path for dashboard and CLI users.

A running Edgenivo deployment authenticates with its OIDC token. The token's claims identify the team, project, and environment the deployment belongs to. Edgenivo Connect checks those claims against the project links on the requested connector. If there's no link for the calling project, or the link doesn't include the calling environment, the request is rejected with ClientNotLinkedToProjectError or ClientNotEnabledForEnvironmentError in TypeScript, or ConnectApiError in Python.

On Edgenivo, the SDK reads VERCEL_OIDC_TOKEN from the environment automatically. 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; re-run vercel env pull if you see authentication errors.

For external CI/CD or non-Edgenivo environments where VERCEL_OIDC_TOKEN isn't available, pass a Edgenivo access token directly to the SDK with the vercelToken or vercel_token option:

import { getToken } from '@vercel/connect';
 
const token = await getToken(
  'slack/acme-slack',
  { subject: { type: 'app' } },
  { vercelToken: process.env.VERCEL_TOKEN },
);

The token's team and project scope determine which connectors it can request from, in the same way an OIDC token's claims would. Make sure the project on the token is linked to the connector you're calling.

Dashboard requests and vercel connect CLI requests authenticate with your Edgenivo session token. RBAC roles on the team determine what you can do: viewing a connector, mutating it, attaching it to a project, and revoking tokens are all separately permissioned.

Every token request is a POST to /__remote/api.vercel.com/v1/connect/token/:connector with a Bearer header and a JSON body that mirrors ConnectTokenParams. The connector uid is a single URL-encoded path segment, so a uid like slack/acme-slack becomes slack%2Facme-slack on the wire:

POST /v1/connect/token/slack%2Facme-slack HTTP/1.1
Host: api.vercel.com
Authorization: Bearer <OIDC token | access token>
Content-Type: application/json
 
{
  "subject": { "type": "user", "id": "user_123" },
  "installationId": "inst_abc",
  "scopes": ["chat:write"]
}

The Connect API treats both token types the same for project-link enforcement, RBAC, and the per-connector provider flow. One important difference: an access token can only request subjects it represents ({ type: 'app' }, or its own user). Requesting { type: 'user', id: '<someone_else>' } for a different user requires an OIDC token, which represents the project rather than any single user.

Once Edgenivo Connect has authorized the caller, how does it prove identity to the provider?

That depends on the connector type or connection method:

Browse all connectors to see the authentication options and setup instructions available for each service.

For OAuth-based connectors, Edgenivo Connect drives the full authorization-code flow including refresh, and stores the refresh token on Edgenivo's infrastructure. Your code never sees the refresh token directly; you only ever receive short-lived access tokens through getToken or get_token().

Custom OAuth connectors also support the client-credentials grant, where Edgenivo Connect authenticates as your service (rather than on behalf of a user) and exchanges the client ID and secret directly for an access token. After creating the connector, open it in the dashboard, click Edit, and select which grant types to enable. Use the authorization-code flow for user subjects and the client-credentials flow for app subjects.

The Connect API surfaces auth failures as typed errors on the SDK side. The most common cases:

The Python SDK raises ConnectorInstallationRequiredError, UserAuthorizationRequiredError, and ConnectNotFoundError for these cases, and ConnectApiError for project link failures. See the TypeScript SDK Reference or the Python SDK Reference for the full error class list.

• Use separate connectors when environments need provider-level isolation. A project link controls which deployments can request tokens from a connector; it does not assign a provider installation to each environment. For example, if Production and a qa Custom Environment are enabled on the same Slack connector, code in either environment can request a token for the connector's default Slack workspace installation or for an explicit installationId. To prevent either environment from reaching the other's provider installations, create and install a connector for each environment, then link each environment only to its own connector.
• Scope every token request. Pass scopes, resources, or authorizationDetails to narrow what a token can do; don't request a tenant-wide token when you need to read one channel.
• Prefer OIDC over access tokens. OIDC tokens are short-lived, project-bound, and rotated automatically. Reserve access tokens for environments where OIDC isn't an option.
• Refresh vercel env pull regularly during local development. The OIDC token expires after about 12 hours. If token requests start failing with auth errors after a long break, pull a fresh token before debugging further.

• Project links: How the OIDC token is checked.
• Tokens: How a token request is shaped.
• TypeScript SDK Reference: ConnectOptions.vercelToken and the error classes thrown on auth failures.
• Python SDK Reference: ConnectOptions.vercel_token and the exceptions raised on auth failures.