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 does | Docs | |--------------|--------------|------| | LoginForm | Complete login form; handles forgot password, magic link, passkeys, MFA, and workspace selection inline | Email & password | | SignupForm | Signup with email, first name, and last name | Signup | | SsoButton | Standalone SSO button, redirect or popup mode | SSO login button | | MagicLink | Magic link request form | Magic link | | ForgotPassword | Request and reset modes for password resets | Forgot / reset password | | MfaChallenge, MfaSetup | MFA code challenge and first-time setup | MFA / 2FA | | PasskeyLogin, PasskeySetup, PasskeyRequestSetupLink | Passkey (WebAuthn) login and registration | Passkeys | | TenantSelector, WorkspaceSelector | Pick a workspace at login; switch workspaces later | Switching workspaces | | TeamManagementPanel | Invite users, change roles, edit workspace settings | User & team management | | ApiTokenManagement | Self-service API token management | Tokens |

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 reads the cookie-based session set by the hosted-login callback; apps using the drop-in LoginForm (tokens in localStorage) protect pages client-side with <ProtectedRoute redirectTo="/auth/login"> instead. See Route guards.

Identity, roles, and workspaces

Section titled “Identity, roles, and workspaces”