Vercel Passport Is GA: Deployments That Know Who Your Users Are

Last updated: October 18, 2026

Updated October 18, 2026: The getIdentity, verifyIdentity, subject and externalSubject names in this post check out against the published @vercel/passport 1.2.0 types. One fix: in the package's TypeScript types, extra claims on identity.payload are typed unknown, so the group-check sample now narrows groups with Array.isArray before calling .includes(). Vercel's own additional identity scopes example reads the same identity?.payload.groups value.

Vercel Passport is now generally available. It turns any deployment into a gated application: visitors authenticate through Okta, Microsoft Entra ID, or any OIDC provider before they see a byte of your app, and your code receives a signed, verified identity instead of a shared password or a vague proxy header.

Deployment protection on Vercel used to be a blunt instrument. A shared password for previews, or Vercel's own SSO for your team. What it could not do was let the application itself know who was looking. Passport closes that gap: the identity provider sits in front of the request, and a signed token carries the visitor's identity through to your code.

What changed#

Passport runs in Vercel's network, before your deployment's routes and proxy functions execute. Unauthenticated browser visitors are redirected to your identity provider before they ever reach your application code. After a successful exchange, Vercel injects a signed identity token into the request.

The client-side contract is a single helper in a new package:

npm install @vercel/passport

import { getIdentity } from '@vercel/passport';

export async function GET() {
  const identity = await getIdentity();
  if (!identity) {
    return Response.json({ error: 'Unauthorized' }, { status: 401 });
  }
  return Response.json(identity);
}

Two details make this different from rolling your own auth proxy:

1. Vercel strips any client-supplied value for the x-vercel-oidc-passport-token header and injects its own verified token, so a visitor cannot forge an identity by setting a header.
2. getIdentity() returns null for bypassed or unauthenticated requests, giving you one canonical way to test for a signed-in visitor. In local development it returns a configurable development identity, so the same code path runs without a real identity provider.

The identity payload carries a subject, a stable identifier scoped to your team and the Vercel Connect application that links Passport to your identity provider, plus an externalSubject, the visitor's ID inside the provider itself. That split matters: subject stays stable even if the visitor's provider-side ID changes, so you can key sessions and audit trails on it.

Group-based authorization is built in#

Passport can now carry additional identity claims from your provider, starting with group membership. You request the groups scope and allowlist the claim in the Vercel Connect application, then read it directly from the identity payload:

import { getIdentity } from '@vercel/passport';

export async function GET() {
  const identity = await getIdentity();
  const claim = identity?.payload.groups;
  const groups = Array.isArray(claim) ? claim : [];
  if (!groups.includes('engineering')) {
    return Response.json({ error: 'Forbidden' }, { status: 403 });
  }
  return Response.json({ groups });
}

This is the shape of real authorization, not just authentication. A deployment protected by Passport can serve the same route to everyone, but only hand over admin data to members of a specific group. One gate at the edge, fine-grained checks in code.

Forwarding identity to downstream services#

The token is not confined to the deployment it protected. You can forward it to another backend as a bearer token and verify it there with verifyIdentity(), available in @vercel/passport 1.0.0 and later. The helper checks the token signature, the Passport claims, and that the token came from the expected project and environment:

import { verifyIdentity } from '@vercel/passport';

export async function GET(request) {
  try {
    const identity = await verifyIdentity(request, {
      ownerId: 'team_your_team_id_here',
      projectId: 'prj_your_project_id_here',
      environment: 'production',
    });
    return Response.json({ subject: identity.subject });
  } catch {
    return Response.json({ error: 'Unauthorized' }, { status: 401 });
  }
}

Non-JavaScript services can verify the token as a standard JWT against the published JWKS endpoint at passport.vercel.com/.well-known/jwks.json. So a Python worker or a Go service can trust the same identity without sharing secrets.

The operational details that matter#

Every successful Passport authentication records a passport-access-granted event in both the Activity Log and Audit Logs, identifying the visitor and recording the protected hostname and project. That is the difference between "someone opened the preview" and "Marco from engineering opened the preview at 14:03".

Two bypass paths keep automation working:

• Protection Bypass for Automation: webhooks, cron jobs, and CI runs that already send a bypass secret in the x-vercel-protection-bypass header or query parameter keep working. Because Passport runs before your routes and proxy functions, the secret must be part of the original request rather than added by your own middleware.
• Trusted Sources: the same bypass without a shared secret, using short-lived OIDC tokens from the Vercel projects and external services you authorize. This is how a workflow that triggers Vercel's open source agent framework eve from Slack can reach a Passport-protected deployment.

Custom environments are supported, so staging and qa deployments get the same identity provider sign-in as previews and production. Passport is available on the Enterprise plan.

Why it matters to developers#

The interesting thing about Passport is what it removes from your to-do list. Building auth-gated previews for customers, internal tooling, or demo environments has always meant standing up a proxy, managing session state, and hand-rolling identity plumbing that has nothing to do with your product. Passport moves that responsibility to the platform: Vercel owns the redirect, the token lifecycle, and the security boundary, and your code gets a typed identity object.

It also signals where Vercel's security model is going. Together with Better Auth's native Vercel support, the auth ecosystem on the platform is converging on real identity rather than shared secrets. Passport sits at the edge, while libraries like Better Auth handle identity inside your app; for teams that want every deployment to carry a verified visitor identity, Passport replaces the edge layer entirely.

For agent-heavy workflows the fit is natural. Zero-touch OAuth patterns, which solve the browser-auth problem for agents, pair with Passport's Trusted Sources bypass to let CI and agent frameworks reach protected deployments without human intervention. The token model also complements Vercel's durable execution programming model: a long-running workflow can forward the verified identity of its triggerer through every step.

If you ship internal tools or customer previews on Vercel, this is the easiest upgrade you will make this year. Enable Passport, point it at your existing OIDC provider, and delete the password-gate code.

FAQ#

What is Vercel Passport?#

Passport puts an identity provider in front of a Vercel deployment. Visitors authenticate through Okta, Microsoft Entra ID, or any OIDC provider before reaching your app, and Vercel injects a signed identity token that your code reads with getIdentity() from @vercel/passport.

How do I check group membership with Vercel Passport?#

Request the groups scope and allowlist the claim in the Vercel Connect application, then read identity.payload.groups from the object getIdentity() returns and check for the group you need, for example returning a 403 when engineering is missing.

Can other backend services verify a Vercel Passport identity?#

Yes. Forward the token as a bearer token and verify it with verifyIdentity() in @vercel/passport 1.0.0 and later, which checks the signature, the Passport claims, and the expected project and environment. Non-JavaScript services can verify it as a standard JWT against the JWKS endpoint at passport.vercel.com/.well-known/jwks.json.

Do webhooks and CI still work on a Passport-protected deployment?#

Yes, through Protection Bypass for Automation, which keeps requests that send a bypass secret in the x-vercel-protection-bypass header or query parameter working, and through Trusted Sources, which uses short-lived OIDC tokens instead of a shared secret.

Which Vercel plan includes Passport?#

Passport is available on the Enterprise plan.

Continue Reading#

• Better Auth Joins Vercel: What It Means for the Auth Ecosystem - where app-level auth on Vercel is heading
• AI Agent Auth Platforms Compared - how the agent auth providers handle the same problem
• Zero-Touch OAuth for MCP: Enterprise Auth Gets Practical - browser-free auth for automated workloads
• Vercel eve: The Framework for Building AI Agents - the agent framework Passport's Trusted Sources bypass supports
• Vercel's New Durable Execution Programming Model - long-running workflows that can carry verified identity

Sources#

• Vercel Passport is now generally available - Vercel Changelog, July 31, 2026
• Vercel Passport documentation - Vercel docs
• Read identity with getIdentity() - Vercel docs
• Verify identity in downstream services - Vercel docs
• Additional identity scopes - Vercel docs
• Trusted Sources for Deployment Protection - Vercel Changelog