HTTP Operations

HTTP operation services expose effect-auth's standard workflows as endpoint-shaped functions without fixing the application API's routes or group layout. Import each service, live layer, contract, and endpoint from its canonical @effect-auth/core/HttpApi/<Feature> path. Reserve @effect-auth/core/HttpApi for shared HTTP infrastructure and cross-feature composition such as CoreAuthHttpApiLive. For the ownership boundary and composition model, see HTTP Operations; for binding examples, see Custom Auth API.

import {
  SessionHttpApiGroup,
  SessionHttpOperations,
  SessionHttpOperationsLive,
  currentSessionEndpoint,
} from "@effect-auth/core/HttpApi/Session";

Export pattern

For a feature named Name, the public exports follow a consistent pattern:

Each method is a typed HttpOperation<typeof endpoint, Requirements>: a function taking the built-in endpoint handler request with Effect's internal endpoint and group fields omitted, and returning an Effect with that endpoint's success, error, and service requirements. Requirements defaults to never, and most existing live layers capture their dependencies during construction. Effect-native operations such as permission-definition administration resolve their explicit requirements during execution; their focused preset installs the matching router middleware. A custom endpoint must still declare schemas compatible with the method's request, success, and errors.

The feature name in the service maps directly to the subpath. For example, use HttpApi/EmailVerification, HttpApi/RecoveryCodes, HttpApi/OAuthProviderAuthorization, HttpApi/JwtDiscovery, and HttpApi/AdminTrustedDevice for those services. The focused module exports only that feature's public HTTP surface; it does not act as another broad barrel.

Catalog

The requirements column is deliberately high-level. Configuration services, stores, cryptography, and optional capabilities are summarized rather than presented as an exhaustive layer type.

Primary authentication

Sessions, MFA, and assurance

Account and administration

Tokens and federation

Layer and boundary semantics

Construct the feature service by providing its live layer, then yield the service in an HttpApiBuilder group and bind only the desired methods. A layer constructs the complete service even when the API exposes one method. Optional services are detected and captured at layer construction; providing one only around a later method call does not enable it.

Some operations capture and execute standard AuthRateLimit; others enforce authentication or authorization through sessions and feature-specific services, and public discovery or protocol operations may require neither. Do not add the same standard security check around an operation that already executes it. Custom origin/CSRF, decoding, tenant, role, and other application middleware remains part of the endpoint boundary.

AdminPermissionDefinitionHttpOperations authenticates the current session and calls AdminPermissionDefinitionAuthorization before every definition lookup or mutation. The operations obtain permission administration, sessions, cookies, and authorization services when the request runs rather than through exported handler factories. The focused preset installs AdminPermissionDefinitionHttpRequirementsLive to provide that context to its routes. The library deliberately provides no allow-all authorization layer. Mutations emit typed audit events when request audit wiring is present. Its list operation uses an after cursor and a bounded limit from 1 through 100 (default 50). This standalone API is not mounted by CoreAuthHttpApiLive, and grant metadata is not exposed through it.

Session issuance, rotation, revocation, and clearing use AuthHttp and/or SessionCookie where the workflow requires them. Related continuation, trusted-device, and login-approval cookies are applied only for configured workflows. Cookie-capable operations do not remove the need for origin protection on the API. Expected domain failures are mapped to stable public errors; unexpected infrastructure failures are sanitized.

To discover exact requirements, inspect the exported layer type rather than this summary:

import { PasswordHttpOperationsLive } from "@effect-auth/core/HttpApi/Password";
import type { Layer } from "effect";

type Requirements<L> =
  L extends Layer.Layer<unknown, unknown, infer R> ? R : never;
type PasswordRequirements = Requirements<typeof PasswordHttpOperationsLive>;

Editor hover or “go to type definition” on PasswordRequirements shows the current required context. Effect.serviceOption(...) capabilities do not appear as mandatory requirements; inspect the live layer implementation or feature documentation when deciding which optional behavior to enable.