Getting the user token

There’s no store to read and no token to fetch yourself. bridge.auth() / bridge.protect(...) verify the incoming Authorization: Bearer header (or x-api-key) and attach the decoded result to the Express Request before your handler runs. See Route guards for when that happens in the request lifecycle.

The recommended path: req.bridgeUser and req.bridgeTenant

import { Router } from 'express';

const router = Router();

router.get('/items', (req, res) => {
  const user = req.bridgeUser!;
  const tenant = req.bridgeTenant;
  res.json({ requestedBy: user.email, tenant: tenant?.name });
});

export default router;

Bridge Express augments the Express Request type via declaration merging, so req.bridgeUser, req.bridgeTenant, req.bridgeAccessToken, and req.bridgeApiToken are all typed and available without extra setup. req.bridgeUser and req.bridgeTenant only ever hold a value on a user JWT request; an API-token-only request has neither set, since API tokens don’t carry a user or workspace identity the same way (see API tokens).

BridgeUser is populated straight off the verified JWT claims. There’s no separate “minimal identity” vs. “full profile” split the way a frontend often has (one lean reactive object plus a richer profile fetch); this one object already carries everything decoded from the token:

Field	Type	Description
id	string	User ID (sub claim)
email	string	Email address
emailVerified	boolean	Email verification status
username	string	Username (preferred_username, falls back to email)
fullName	string	Full display name
givenName / familyName	string | undefined	First / last name
locale	string | undefined	User’s locale
onboarded	boolean | undefined	Whether onboarding is complete
tenantId	string	ID of the workspace this token was issued for (a workspace is called a tenant in the API)
appId	string | undefined	App ID the token was issued for (aid claim)
scope	string | undefined	OAuth scopes on the token
role	string | undefined	User’s role in this workspace
privileges	string[] | undefined	Privilege keys from the JWT privileges claim
multiTenantAccess	boolean | undefined	Whether the user can access more than one workspace

BridgeTenant is similarly decoded from the token’s tenant claims (tid/tenant_id, tenant_name, tenant_locale, tenant_logo, tenant_onboarded):

Field	Type	Description
id	string	Workspace (tenant) ID
name	string	Workspace name
locale	string | undefined	Workspace locale preference
logo	string | undefined	Workspace logo URL
onboarded	boolean | undefined	Whether the workspace has completed onboarding

If the token carries no tenant claim, transformJwtToBridgeTenant returns null and req.bridgeTenant is undefined.

Reading the API-token path

req.bridgeApiToken is the counterpart on the machine-to-machine path, set when the request authenticated via x-api-key instead of (or alongside) a user JWT:

router.get('/api/status', bridge.protect(), (req, res) => {
  res.json({
    user: req.bridgeUser,          // set on the user-JWT path
    apiToken: req.bridgeApiToken,  // set on the API-token path; see API tokens
  });
});

Field	Type	Description
sub	string	Token subject identifier
appId	string	App ID the token was issued for
tenantId	string | null	Workspace (tenant) ID; null for app-level tokens
type	'api'	Always 'api' for API tokens
privileges	string[]	Privilege strings (e.g. ['USER_READ', 'TENANT_WRITE'])
exp	number | undefined	Expiry (epoch seconds)

Both a user JWT and an API token can be present and valid on the same request at once; see API tokens for dual-credential requests.

The raw access token: req.bridgeAccessToken

You almost never need this either, but when your handler needs to call another Bridge-aware backend on the caller’s behalf (a downstream service, or Bridge’s own API), forward the verified token instead of re-deriving credentials:

router.get('/items/from-service-b', async (req, res) => {
  const data = await bridge.http.get('http://service-b/items', req.bridgeAccessToken);
  res.json(data);
});

req.bridgeAccessToken is only set on the user-JWT path (it’s the exact bearer token the middleware just verified). This is the backend counterpart to a frontend tokenStore, except there’s no refreshing to think about: your handler only ever sees a token that has already been validated for this request, and you’re not responsible for its lifetime.

Tenant-scoped data beyond the JWT: bridge.fromJwt()

req.bridgeTenant only gives you what’s baked into the JWT (id, name, locale, logo, onboarded). For subscription plan, entitlements, or branding, use bridge.fromJwt(req.bridgeAccessToken!), which fetches (and short-TTL-caches) a fuller snapshot for the token’s workspace:

router.get('/billing/plan', async (req, res) => {
  const tenant = bridge.fromJwt(req.bridgeAccessToken!);
  res.json(await tenant.subscription);
});

See How the token is kept current for how fresh this snapshot is relative to the JWT-decoded fields, and Multi-tenancy for how tenant scoping is enforced.