---
title: "Configuration"
url: "https://effect-auth.itsbroly.com/reference/configuration/"
description: "Reference the public effect-auth configuration surface."
---



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 [#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 [#minimal-layer]

```ts title="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 [#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 [#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](/concepts/sessions/)
and [Security policies](/concepts/security-policies/) for behavior rather than
an every-property listing.

## HTTP configuration [#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 [#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](/authentication/password/),
[Magic links](/authentication/magic-links/), [Email OTP](/authentication/email-otp/),
[Passkeys](/authentication/passkeys/), [TOTP](/authentication/totp/), and
[Recovery codes](/authentication/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](/reference/package-exports/).