Configuration

Effect Auth configuration is a graph of Effect services and layers, not one global object. The application reads environment variables, validates them, and supplies library values. Names such as AUTH_SECRET and AUTH_ALLOWED_ORIGINS are application conventions used in examples; they are not read by Effect Auth and have no library-defined defaults.

Configuration map

Owner	Public API	Scope
Application	runtime env/config, storage, `Mailer`, URL builders	Deployment-specific values and infrastructure
Domain	`AuthSecretsLive`, `AuthSecretsFromRootLive`, `AuthDomainConfigLive`	Secrets, sessions, cookies, challenges, privacy, verification-session policy
HTTP preset	`AuthHttpApiConfigLive` and feature `*HttpConfigLive` layers	Request security and built-in route behavior
Feature	`PasswordDefaultLive(...)`, `MagicLinkLoginLive(...)`, etc.	Algorithms and feature-specific policy

Configuration layers are optional only where their referenced service has a default. Required services, such as cryptography, storage, mail delivery, and some feature settings, must still be provided to the final layer graph.

Minimal layer

auth-config.ts

import { Duration, Layer, Redacted } from "effect";
import {
  AuthDomainConfigLive,
  AuthSecretsFromRootLive,
} from "@effect-auth/core/AuthConfig";
import { WebCryptoLive } from "@effect-auth/core/Crypto";
import { AuthHttpApiConfigLive } from "@effect-auth/core/HttpApi";

const CryptoLive = WebCryptoLive();

export const AuthConfigLive = Layer.mergeAll(
  AuthSecretsFromRootLive({
    root: Redacted.make(process.env.AUTH_SECRET!),
  }).pipe(Layer.provide(CryptoLive)),
  AuthDomainConfigLive({
    sessions: {
      ttl: {
        idleTtl: Duration.days(30),
        absoluteTtl: Duration.days(90),
        refreshAfter: Duration.days(1),
      },
    },
    sessionCookie: { name: "__Host-session", secure: true },
  }),
  AuthHttpApiConfigLive({
    originCheck: { allowedOrigins: "https://app.example.com" },
    requestMetadata: { trustProxyHeaders: false },
  }),
  CryptoLive
);

process.env.AUTH_SECRET above is deliberately application code. Decode and validate deployment configuration rather than relying on the non-null assertion shown in this compact example.

Secrets and crypto

Choice	Behavior
`AuthSecretsFromRootLive({ root, namespace? })`	Derives independent session, challenge, and privacy HMAC keys. `namespace` defaults to `"auth.secret.v1"`; requires a `Crypto` service while constructing the layer.
`AuthSecretsLive({ session, challenge, privacy })`	Supplies three separately managed `CryptoKey` values; there are no secret defaults.
`WebCryptoLive(options?)`	Supplies the built-in Web Crypto implementation. A runtime may instead provide its own `Crypto` service.

Use Redacted.make(...) for textual keys. Keep the root stable: changing it, the namespace, or an individual session key invalidates corresponding signed state. Separate keys are useful when the deployment requires independent rotation; root derivation is the simpler default.

Domain configuration

AuthDomainConfigLive installs only the fields supplied. Omitted fields use their Context.Reference defaults (empty option objects).

Field	Important values and defaults
`sessions`	`ttl`, `sessionIdBytes`, `sessionSecretBytes`. TTL defaults are idle 30 days, absolute 90 days, refresh after 1 day. Durations use `effect/Duration`, not milliseconds.
`sessionCookie`	`name` `"__Host-session"`, `secure: true`, `httpOnly: true`, `sameSite: "lax"`, `path: "/"`; `domain` is absent. A `__Host-` name always forces secure, `/`, and no domain.
`challenge`	Challenge lifetime/entropy policy used by challenge-backed features.
`privacy`	Privacy-keying options used for protected identifiers and rate-limit keys.
`emailVerificationSessionPolicy`	Controls whether unverified users receive no session or a limited session.

The complete contracts are AuthDomainConfigOptions, SessionsOptions, and SessionCookieOptions in the package types/source. See Sessions and Security policies for behavior rather than an every-property listing.

HTTP configuration

AuthHttpApiConfigLive configures middleware used by the built-in HTTP APIs:

Field	Meaning and default
`originCheck.allowedOrigins`	Extra browser origins as a string, comma-separated string, or array. Same-origin requests are accepted. Default: none extra.
`originCheck.allowMissingOrigin`	Allows unsafe requests with neither `Origin` nor `Referer`. Default: `true`; set `false` for browser-only endpoints when non-browser clients are not required.
`requestMetadata.trustProxyHeaders`	Reads client IP from Cloudflare/forwarded IP headers. Default: `false`. Enable only behind a trusted proxy that removes spoofed values.

This layer does not configure CSRF cookie/header names; those belong to the specific middleware API. Built-in feature route options use separate layers: PasskeyHttpConfigLive, TotpHttpConfigLive, RecoveryCodeHttpConfigLive, OAuthHttpConfigLive, OAuthTokenHttpConfigLive, RefreshTokenHttpConfigLive, and JwtHttpConfigLive. OAuth provider credentials and provider definitions are application-supplied OAuth services/configuration; they are not fields of AuthHttpApiConfigLive.

Feature-owned values

Category	Configure at
Email transport/from address	Provide `Mailer`, templates, and `AuthMailerLive({ from? })`; the library does not infer SMTP or sender environment variables.
Public links	Pass `makeUrl` to magic-link/password-reset feature layers. There is no global public/base URL setting.
Passkey RP	`PasskeyHttpConfigLive` receives `relyingParty: { id, name }` for preset routes; the RP ID is a domain, not a URL.
Password/email OTP/magic link	Their feature layer options own hashing, expiry, token, and URL policy.
OAuth	Provider registry/configuration, OAuth flow services, and the HTTP/OAuth-token config layers own distinct concerns.

Canonical setup and security guidance lives on Password, Magic links, Email OTP, Passkeys, TOTP, and Recovery codes. For less common knobs, prefer the exported TypeScript types and package source as the authoritative reference; entry points are summarized under Package exports.