Overview

Layeron Auth gives a backend app a typed session product, route-level user authentication, and a consistent user identity shape for Policy and Realtime.

You declare Auth in application code:

import { backend } from "@layeron/core"
import { auth } from "@layeron/modules"

const app = backend()
const appAuth = auth()

app.use(appAuth)

Auth stores its session state through the Layeron Database Product. The compiler creates a Layeron-managed internal database for Auth state, adds migrations, and connects the app Worker to the Auth Product Worker through Service Binding RPC.

What Auth Covers

Auth currently covers the foundation that other backend capabilities need:

• Session creation with secure random access tokens.
• Refresh tokens with rotation, reuse detection, and family revocation.
• Cookie, bearer, or combined token transport.
• Access token verification.
• Session lookup, sign-out, single-session revocation, and all-session revocation.
• User lookup through managed, mapped, custom, or external storage.
• Email/password sign-up.
• Password sign-in with optional Email OTP and remember tokens.
• Password updates with current-password checks and optional Email OTP.
• Password reset emails with one-time hashed tokens.
• GitHub login with OAuth code exchange, verified email lookup, identity linking, and Auth session creation.
• OIDC login with discovery, PKCE, nonce, state, JWKS verification, identity linking, and Auth session creation.
• Passkey registration, passkey login, and passkey MFA or step-up verification through WebAuthn ceremonies.
• Structured AuthError codes and JSON error bodies.
• auth: "user" route protection.
• Auth subject resolution for Policy and Realtime.
• Argon2id password hashing by default, with PBKDF2-SHA256 available for SHA-256 based compatibility.

Storage Modes

Auth has five user storage modes:

Mode	Auth stores	Application stores
managed	Sessions, core user fields, tenant field, anonymous flag, roles, scopes, attributes, app metadata, user metadata.	Login-specific data outside the Auth user record.
managed_core	Sessions and core user fields.	Roles, scopes, tenant mapping, and application metadata.
mapped	Sessions, refresh tokens, identities, credentials, challenges, and MFA state.	User profiles in a mapped Database product table.
custom	Sessions and access token hashes.	Every user field. Auth calls application functions to resolve users.
external	Login, sessions, refresh tokens, identities, credentials, and challenges.	Every user profile field in an external resolver.

Route Auth

Set auth: "user" on a route to require an active Auth session:

app.get("/api/profile", { auth: "user" }, async () => {
  const user = await appAuth.getUser()

  return user
})

The Gateway verifies the token with the Auth Product Worker before the handler runs. Realtime can then use the route auth context when autoResolveUser is enabled.

Next Steps

• Get started: Add Auth, create users and sessions, and protect routes.
• User storage modes: Choose managed, managed core, custom, mapped, or external user storage.
• GitHub login: Configure a GitHub OAuth provider and verify callback results.
• OIDC login: Configure a generic OpenID Connect provider with PKCE and token endpoint settings.
• Passkeys: Add WebAuthn credentials, browser encoding, MFA, and passkey management.
• API reference: Review Auth options, operations, errors, and result contracts.