Skip to content
The Bridge Logo The Bridge docs

Authentication

Section titled “Authentication”

Bridge gives your Next.js app a complete authentication system without you building one: sign-in flows (email and password, magic link, passkeys, Google and Azure AD SSO, MFA), signup, drop-in UI components for all of them, route protection, roles and privileges, multi-workspace support, and self-service API tokens. You configure what’s enabled in Control Center (your admin dashboard at app.thebridge.dev) or the CLI; the SDK components pick it up automatically.

The mental model

Section titled “The mental model”

Three ideas carry the whole section:

  • The bridge object. One import that exposes the signed-in user and their workspace as reactive stores: bridge.user (id, email, role, tenantId) and bridge.tenant.* (the workspace; a workspace is called a tenant in the API). Read them with the useBridgeReadable() hook and your UI stays current.
  • Auth states. A single useAuthState() hook tracks where the user is in the login flow, from 'unauthenticated' through steps like 'mfa-required' and 'tenant-selection' to 'authenticated'. The drop-in LoginForm walks these states for you; you can also branch on them yourself. See Auth states.
  • The live channel. A persistent realtime connection the SDK maintains. When a role, plan, or permission changes server-side, Bridge pushes the change down the channel and your stores update in place, with no reload or polling. See Live Updates.

Sessions are JWT-based: signing in stores a token set in localStorage, and Bridge refreshes it before expiry. Signing out erases the stored token. See Logging in and logging out.

Enabling sign-in methods

Section titled “Enabling sign-in methods”

Each method is a per-app setting, flipped on in Control Center or via the CLI:

Drop-in UI components

Section titled “Drop-in UI components”

Every flow has a ready-made component, imported from @nebulr-group/bridge-nextjs/client. They render inside your app with no external redirects, and all accept standard HTML attributes (className, style, data-*) alongside their own props.

Component(s)What it doesDocs
LoginFormComplete login form; handles forgot password, magic link, passkeys, MFA, and workspace selection inlineEmail & password
SignupFormSignup with email, first name, and last nameSignup
SsoButtonStandalone SSO button, redirect or popup modeSSO login button
MagicLinkMagic link request formMagic link
ForgotPasswordRequest and reset modes for password resetsForgot / reset password
MfaChallenge, MfaSetupMFA code challenge and first-time setupMFA / 2FA
PasskeyLogin, PasskeySetup, PasskeyRequestSetupLinkPasskey (WebAuthn) login and registrationPasskeys
TenantSelector, WorkspaceSelectorPick a workspace at login; switch workspaces laterSwitching workspaces
TeamManagementPanelInvite users, change roles, edit workspace settingsUser & team management
ApiTokenManagementSelf-service API token managementTokens

Protecting routes

Section titled “Protecting routes”

Pass a rules config to withBridgeAuth in middleware.ts to mark routes public or protected. Unauthenticated users are redirected to Bridge’s hosted login page. See Route guards and the config reference.

Framework note: Next.js splits route protection across the server/client boundary. withBridgeAuth runs in middleware.ts and guards hosted-login sessions, which live in cookies; it verifies the session token: its PS256 signature against the Bridge JWKS (<apiBaseUrl>/auth/.well-known/jwks.json), issuer <apiBaseUrl>/auth, audience containing your appId, and expiry. Apps using the drop-in LoginForm (loginRoute set, tokens in the browser) are guarded by <ProtectedRoute redirectTo="/auth/login"> and their API; the middleware steps aside for them. Neither route guard replaces verifying the token in your API. See Route guards.

Identity, roles, and workspaces

Section titled “Identity, roles, and workspaces”