Request authentication states

A frontend Bridge SDK tracks a single reactive authState that walks a signed-in user through a multi-step sign-in flow (credentials, MFA, workspace selection, fully authenticated). An Express backend doesn’t have a sign-in flow to walk through; it evaluates one request at a time, independently, with no memory of the previous one. The useful equivalent here is the set of outcomes bridge.auth() / bridge.protect(...) can land a request in.

The outcomes

| Outcome | HTTP result | What’s on req afterward | |---|---|---| | No credential offered | 401 with WWW-Authenticate: ... error="missing_token" | Nothing; handler never runs | | Malformed Authorization header | 401, error="invalid_token" | Nothing; handler never runs | | Expired user JWT | 401, error="expired_token" | Nothing; handler never runs | | Invalid signature / unknown key / bad issuer or audience | 401, error="invalid_token" | Nothing; handler never runs | | API token issued for a different app | 401, error="invalid_token" | Nothing; handler never runs | | Wrong credential type for this endpoint (acceptAuth) | 401, error="invalid_request" | Nothing; handler never runs | | Valid user JWT, but missing required role / route-rule privilege / featureFlag | 403 Forbidden | req.bridgeUser is set even though the handler never runs | | Valid API token, but missing required privilege | 403 Forbidden | req.bridgeApiToken is set even though the handler never runs | | Valid user JWT only | handler runs | req.bridgeUser, req.bridgeTenant, req.bridgeAccessToken set; req.bridgeApiToken unset | | Valid API token only | handler runs | req.bridgeApiToken set; req.bridgeUser/req.bridgeTenant/req.bridgeAccessToken unset | | Both a valid user JWT and a valid API token | handler runs | All four are set; both contexts coexist on req | | Route marked public (bridge.public() or an ANONYMOUS route rule) | handler runs, no verification attempted | Nothing set; req.bridgeUser/req.bridgeApiToken are undefined |

The two credential paths are evaluated independently: when both an x-api-key and an Authorization: Bearer header are present and valid, both contexts coexist on the request rather than one taking precedence (some Bridge frontends always send both). See API tokens for the full dual-credential story, and Configuration for the exact JSON error bodies.

Checking which state you’re in, inside a handler

For a dual-auth endpoint (the default), branch on which context is present:

router.get('/users', bridge.protect({ privilege: 'USER_READ' }), (req, res) => {
  if (req.bridgeApiToken) {
    // Authenticated via API token (machine caller)
    return res.json({ users: [], tenantId: req.bridgeApiToken.tenantId });
  }

  // Authenticated via user JWT (a signed-in person)
  const user = req.bridgeUser!;
  return res.json({ users: [], tenantId: user.tenantId });
});

Why there’s no “in-progress” state

A frontend’s authState has intermediate states ('credentials-validated', 'mfa-required', 'tenant-selection') because signing in is a multi-step, stateful process that the SDK walks a browser through. Verifying a request has no equivalent multi-step process: a token either verifies against Bridge’s JWKS (or introspection endpoint) right now, in full, or it doesn’t. There’s nothing partial to represent. The MFA challenge, workspace selection (a workspace is called a tenant in the API, hence the state name above), and credential exchange that produced the token already happened upstream, in whichever frontend or CLI flow signed the user in. By the time a request reaches your Express app, that’s all settled into a single bearer token you either accept or reject.