createTheAuth() accepts a TheAuthConfig object. The only required field is database. Everything else is optional and enables features incrementally.
Common development setup
A minimal config for local development with username and password sign-in, theAuth-managed sessions, and no email sending:Top-level options
CIBA async approval flow config. See Approval flows.
Lifecycle hooks for sandboxing and custom validation. See Hooks.
Timeout and failure policy for
beforeAuthorize and beforeAgentCreate. Defaults: 2000 ms, deny on timeout or error for beforeAuthorize, throw for beforeAgentCreate. Environment variables THEAUTH_HOOK_TIMEOUT_MS, THEAUTH_HOOK_ON_TIMEOUT and THEAUTH_HOOK_ON_ERROR set the defaults. See Hook safety.Unified policy engine cache, combine strategy, and audit sampling. See Policy engine.
did:web domain and path. See DIDs.
Base URL for the auth server (e.g. https://auth.example.com). Read by plugins that build callback URLs or decide on secure cookies (OAuth, passkey, OAuth proxy).
"memory" | "database" | SecondaryStorage | { default?, rateLimit?, deviceCodes?, ... }
default:"\"memory\""
Where short-lived state lives: rate limit counters, device login codes and similar. Memory is lost on restart and not shared between instances, so use
"database" or Redis when you run more than one server. See Secondary storage.How plugin endpoint rate limits find the real client IP. Forwarded headers are ignored unless you set the number of proxies you run or a header your edge overwrites (for example
cf-connecting-ip). Without either, all clients share one rate limit bucket. See Rate limiting.Webhook endpoints to notify on auth events. See Webhooks.
Password reset flow. See Password reset config.
theauth.<name> instance property when provided: magicLink, emailOtp, emailVerification, totp, passkey, org, sso, admin, apiKeys, username, phone, captcha, and redirects. Several of these require auth.session as noted in their own pages.
Options that TheAuthConfig declares but createTheAuth() does not act on:
mcp:createTheAuth()does not read it. The OAuth 2.1 authorization server is built withcreateMcpModulefrom@glinr/theauth/mcp, which takes aMcpConfig(see MCP config).theauth.mcpon the instance is only the MCP tool server registry.secret: not read bycreateTheAuth(). Set the session secret inauth.session.secretand the MCP signing secret inMcpConfig.signingSecret.emitAgenticJwtClaims: not read bycreateTheAuth(). See Standards for the places it does work.
trust or telemetry option. The trust module is always created with its defaults.
Database config
File path for SQLite, connection string for Postgres/MySQL. Required for every provider except D1.
Skip automatic CREATE TABLE IF NOT EXISTS on init. Use when you manage migrations externally (Flyway, drizzle-kit push, etc.). Defaults to false.
Agent config
Controls the agent identity lifecycle.Required by the type, but not read: agent management is always available. Set it to
true.Maximum number of active agents per owner.
agent.create() throws when the owner is at the limit.Write every
authorize() outcome (allowed and denied) to the audit log. This includes attempts by revoked or expired agents (reason agent_revoked or agent_expired). Unknown agent ids and unknown tokens write no row. When false, no rows are written by the permission engine at all.Default agent lifetime when
agent.create() is called without expiresAt. Format is a number followed by s, m, h, or d (for example "30m", "24h", "7d"); anything else makes create() throw. Every agent therefore has an expiry unless you pass expiresAt.MCP config
Options for the OAuth 2.1 authorization server for MCP-compliant tool access. These are the fields ofMcpConfig, passed to createMcpModule from @glinr/theauth/mcp (see MCP). Passing them as the mcp option of createTheAuth() has no effect today.
Secret used to sign JWTs. At least 32 characters;
createMcpModule throws without it. It does not fall back to any other secret.OAuth clients registered at startup (first-party apps, CLIs, test fixtures).
Async function to add custom claims to issued tokens.
Supplies the values for those claims.
Auth config
Connects theAuth to your existing auth provider so it can resolve the human user behind incoming requests.auth is omitted, theauth.auth.resolveUser() always returns null (manual user management mode).
Built-in adapters exported from @glinr/theauth/auth include betterAuthAdapter, authJsAdapter, clerkAdapter, bearerAuth, cookieAuth, headerAuth, apiKeyAdapter, and customAuth.
Secret rotation
Secrets that sign or encrypt data accept a list so you can rotate without invalidating what is already issued:secret: [current, ...previous]. The first entry signs and encrypts, every entry verifies and decrypts. Add the new secret at the front and deploy, then remove the old one after the longest lifetime of anything it signed. Entries can also be { id, secret }, and the id is emitted with the signature (X-TheAuth-Key-Id for webhooks, a cookie field for sessions) so verifiers try that key first. Entries must be at least 32 bytes, and empty or duplicate entries throw at startup. The list form is supported by webhook endpoint secret (see Webhooks), createStatelessSessions and createSessionCookieCache (see Session hardening). auth.session.secret and McpConfig.signingSecret remain single strings.
Session config
Declared on the type but not read: plugins that set the session cookie (OAuth, passkey) and the default token lookup always use
theauth_session. To rename the cookie, use sessionName on createCookieSessionManager (see Cookie options).Maximum non-expired sessions per user. Enforced inside
sessionManager.create. Impersonation sessions are not counted.What to do when
maxConcurrent is reached. reject makes create throw MultiSessionLimitError.Called after sessions are revoked by
revoke, revokeAll or limit eviction. Errors are swallowed. Used to fan out OIDC back-channel logout.Sign-in gate config
A top-levelsignInGate option. It controls forced password changes, required second factors and trusted devices on every session-issuing path. Without it only the forced password change is enforced. See Sign-in gate for the response shapes and routes.
Array<'password' | 'social' | 'magic_link' | 'passkey'>
default:"['password', 'social', 'magic_link']"
Methods that must pass a second factor when the user has one enabled. The default applies once the
signInGate block is present. With no block, no method requires one.{ enabled, trustDurationSeconds, maxDevices, cookieName }. Off unless enabled is true. Defaults are 30 days, 10 devices and theauth_trusted_device.Password reset config
A top-levelpasswordReset option (not nested under auth). It requires auth.session, and its flow relies on the username module, so configure username too. If auth.session is missing, theauth.passwordReset is null. The caller provides an email-sending callback.
Callback to deliver the reset email. Receives email, raw token, and constructed URL.
Session freshness config
Controls when sessions are considered “fresh” for sensitive operations. Pass it as the top-levelsessionFreshness option; it backs theauth.sessionFreshness.
Plugins
Plugins are factories passed in theplugins array. They register HTTP endpoints and lifecycle hooks. All of these are exported from @glinr/theauth/auth:
Email and password is the top-level
emailPassword option (with emailVerification and passwordReset alongside it), see Email and password. The emailPassword() plugin in the separate @glinr/theauth-email package is deprecated. Username and password sign-in is the top-level username option. deviceAuth() (see Device authorization) and agentRegistration() (see Agent registration tokens) are exported from @glinr/theauth/auth too. Multi-session support lives in the session module, see Multi-session.
Environment variables pattern
Never hardcode secrets in config. Pass them through environment variables:Dev vs production example
Next steps
Migration guides
Switch from better-auth, Clerk, or other providers.
Database setup
SQLite, Postgres, or MySQL configuration.
Framework adapters
Mount theAuth on your framework.