Passport token claims
Passport issues a signed JSON Web Token (JWT) after a visitor authenticates. The token combines standard OpenID Connect claims, Vercel deployment context, and identity claims returned through the Connect application.
Claims marked optional only appear when the identity provider or Connect application supplies them. Applications must validate the token before trusting any claim.
| Claim | Required | Description |
|---|---|---|
iss | Yes | Passport issuer. Team-scoped tokens use https://passport.vercel.com/[TEAM_SLUG]. Use iss with sub when storing a visitor identifier. |
sub | Yes | Stable Passport principal within its issuer and Connector application. Treat it as opaque and do not parse it. |
aud | Yes | Audience for the Vercel owner, source project, and environment that minted the token. |
iat | Yes | Unix timestamp when Passport issued the token. |
nbf | Yes | Unix timestamp before which the token is not valid. |
exp | Yes | Unix timestamp after which the token is not valid. |
| Claim | Required | Description |
|---|---|---|
typ | Yes | Token type. Passport tokens use passport. |
owner | Yes | Vercel team slug. |
owner_id | Optional | Vercel team ID. |
project | Optional | Name of the Vercel project that minted the token. |
project_id | Optional | ID of the Vercel project that minted the token. |
environment | Optional | Vercel environment that minted the token, such as production or preview. |
scope | Optional | Host-specific scope for the Passport session. Do not treat this as the list of OAuth scopes requested from the identity provider. |
plan | Optional | Vercel plan recorded when Passport issued the token. |
sid | Optional | Passport session identifier. Do not use it as the visitor identifier. |
| Claim | Required | Description |
|---|---|---|
connector_id | Yes | ID of the Connect application used to authenticate the visitor. |
external_sub | Yes | Subject returned by the identity provider. It is Connector-specific metadata and is not globally unique. |
external_iss | Optional | Issuer reported for the external identity. |
email | Optional | Visitor email returned by the identity provider. |
email_verified | Optional | Whether the identity provider reports the email as verified. |
name | Optional | Visitor name returned by the identity provider. |
tenant_id | Optional | Tenant identifier returned by supported providers. |
installation_id | Optional | Installation identifier returned by supported providers. |
The token can also include allowlisted claims forwarded by Connect, such as groups. Their names and value shapes depend on the identity provider. Validate their presence and type before using them for authorization.
Use sub as the visitor identifier when your application accepts tokens from one Passport issuer. When it accepts more than one issuer, store iss and sub together.
Do not use email, name, sid, or external_sub alone as a global identifier. These values can change, can be absent, or can overlap across identity providers and Connector applications.
Reading or decoding a JWT does not verify it. Before trusting these claims, verify the signature, issuer, audience, validity period, typ, project, and environment. See Verify forwarded Passport tokens.
Was this helpful?