---
title: "Why effect-auth"
url: "https://effect-auth.itsbroly.com/why-effect-auth/"
description: "Learn the design goals behind Effect-native authentication."
---



effect-auth is for applications that use Effect and want authentication in the same service graph. Auth capabilities are Effect services, implementations are Layers, and expected failures remain typed errors until the HTTP boundary projects them into a public response. Dependencies and failure channels stay visible in types rather than behind a global client or callback registry.

The application owns the result. effect-auth does not require a hosted control plane or prescribe the shape of your user domain. You choose the routes, enabled features, database adapter, runtime, deployment, and the point where an authenticated identity becomes an application user. That control also means operating the system, migrations, credentials, email delivery, abuse controls, and production monitoring are your responsibility.

## Choose the boundary per endpoint [#choose-the-boundary-per-endpoint]

The integration levels are not an application-wide setting:

```text
request -> preset contract -> HTTP operation -> domain primitives
              less assembly                 more app ownership
                    \-> runtime services -> storage adapter -> database
```

* **Presets** mount a complete standard contract when its routes and behavior fit.
* **HTTP Operations** let an application-owned API bind selected standard workflows to different routes or groups. They retain documented operation security, public error mapping, orchestration, and cookie consequences, but custom request decoding, group middleware, origin/CSRF handling, and application guards still belong at your endpoint boundary.
* **Primitives** expose domain services for workflows that genuinely differ. Calling them directly also means owning the transport, security policy, auditing, error projection, and session or cookie consequences that were bypassed.

This progression makes customization explicit: use the highest-level component that fits each endpoint, rather than forking a complete auth handler. See [Architecture](/concepts/architecture/) and [Custom API](/guides/custom-auth-api/).

## Explicit infrastructure boundaries [#explicit-infrastructure-boundaries]

Runtime concerns such as randomness, time, hashing, HTTP behavior, email, and configuration enter through services and Layers. Persistence is similarly behind feature-specific store contracts. A storage adapter must preserve the required semantics, including atomic consumption, compare-and-set updates, uniqueness, and token rotation; merely matching table shapes is not sufficient. The maintained storage support and custom-adapter responsibilities are documented in [Storage](/reference/storage/).

Security semantics are attached to the boundary that implements them. Standard operations apply their documented policy and sanitize unexpected infrastructure failures. Application authorization, tenancy, route-specific origin rules, and controls around direct primitive use stay with the application. This avoids implying that composing an auth function automatically secures an arbitrary endpoint.

The documentation is written for mechanical retrieval: pages distinguish contracts from examples, name exact exports, state ownership boundaries, and cross-link related material. This helps people and coding agents find the relevant level without treating snippets as universal recipes.

## Fit and tradeoffs [#fit-and-tradeoffs]

| Good fit                                                            | Not a good fit                                                                  |
| ------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| An Effect application that wants auth in its typed dependency graph | A team that does not want to adopt or operate Effect-based infrastructure       |
| Teams needing app-owned routes, deployment, data, and user mapping  | Teams wanting a hosted dashboard, managed users, and outsourced auth operations |
| APIs that mix standard endpoints with selected custom workflows     | A framework app best served by its mature, tightly integrated auth package      |
| Teams prepared to review security and storage contracts             | Teams expecting primitives to supply endpoint security automatically            |

effect-auth is **alpha software**. APIs and documentation can change, and production adoption requires careful evaluation. Hosted authentication or framework-native auth may be better when operational delegation, ecosystem integrations, administrative tooling, or stability matters more than Effect-native composition. If the tradeoff fits, begin with the [Quick Start](/quick-start/).