--- title: "HTTP Operations" url: "https://effect-auth.itsbroly.com/reference/http-operations/" description: "Reference reusable HTTP operation services." --- 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/` 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](/concepts/http-operations/); for binding examples, see [Custom Auth API](/guides/custom-auth-api/). ```ts import { SessionHttpApiGroup, SessionHttpOperations, SessionHttpOperationsLive, currentSessionEndpoint, } from "@effect-auth/core/HttpApi/Session"; ``` ## Export pattern [#export-pattern] For a feature named `Name`, the public exports follow a consistent pattern: | Export | Purpose | | --------------------------- | ---------------------------------------------------------------------------------------- | | `NameHttpOperationsService` | Structural service interface containing the methods below. | | `NameHttpOperations` | Effect `Context.Service` tag used in handlers. | | `NameHttpOperationsLive` | Layer that constructs the service from domain, HTTP, configuration, and policy services. | | `NameHttpApiLive` | Focused standard-route preset, where one is exported; this is not the operations layer. | Each method is a typed `HttpOperation`: 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 [#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 [#primary-authentication] | Service | Methods | Focused preset | Key required feature/domain services | | --------------------------------- | ------------------------------------------------------------------------------------------------------------------- | ---------------------- | ---------------------------------------------------------------------------------------------------------------- | | `PasswordHttpOperations` | `signIn`, `signUp`, `resetStart`, `resetVerify`, `set`, `change` | None | Password login, registration, reset and management; sessions, cookies, `AuthHttp`, `AuthRateLimit` | | `EmailVerificationHttpOperations` | `start`, `verify` | None | Verification flow and verification; sessions, cookies, `AuthRateLimit` | | `EmailOtpHttpOperations` | `start`, `verify` | None | Email OTP login, `AuthHttp`, `AuthRateLimit` | | `EmailAuthHttpOperations` | `start` | `EmailAuthHttpApiLive` | Email auth orchestration, `AuthRateLimit` | | `MagicLinkHttpOperations` | `start`, `verify` | None | Magic-link login, `AuthHttp`, `AuthRateLimit` | | `PasskeyHttpOperations` | `registerStart`, `registerFinish`, `authenticateStart`, `authenticateFinish`, `listCredentials`, `revokeCredential` | `PasskeyHttpApiLive` | Passkey config/options/verification/credential management; users, sessions, cookies, `AuthHttp`, `AuthRateLimit` | ### Sessions, MFA, and assurance [#sessions-mfa-and-assurance] | Service | Methods | Focused preset | Key required feature/domain services | | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | -------------------------- | ---------------------------------------------------------------------------------------------------------- | | `SessionHttpOperations` | `current`, `refresh`, `logout`, `list`, `revoke`, `revokeOthers` | None | Sessions, session cookie, `AuthHttp` | | `TotpHttpOperations` | `startEnrollment`, `confirmEnrollment`, `verify`, `listFactors`, `revokeFactor` | `TotpHttpApiLive` | TOTP config/factor management; sessions, cookies, `AuthRateLimit` | | `RecoveryCodesHttpOperations` | `generate`, `regenerate`, `verify`, `list`, `revoke` | `RecoveryCodesHttpApiLive` | Recovery-code config/management; sessions, cookies, `AuthRateLimit` | | `MfaHttpOperations` | `options`, `verifyTotp`, `verifyTotpForFlow`, `verifyRecoveryCode`, `verifyRecoveryCodeForFlow`, `startPasskey`, `verifyPasskey` | `MfaHttpApiLive` | Auth-flow state/orchestration, TOTP/recovery/passkey services and config, `AuthHttp`, `AuthRateLimit` | | `StepUpHttpOperations` | `options`, `verifyTotp`, `verifyPassword`, `verifyRecoveryCode`, `startPasskey`, `verifyPasskey` | `StepUpHttpApiLive` | Sessions/cookies, credentials/password hashing, TOTP/recovery/passkey services and config, `AuthRateLimit` | | `LoginApprovalHttpOperations` | `approve`, `status`, `finalize` | None | Login approval, auth flow/state, users, `AuthHttp` | ### Account and administration [#account-and-administration] | Service | Methods | Focused preset | Key required feature/domain services | | ----------------------------------------- | ---------------------------------------------------------------- | -------------------------------------- | ------------------------------------------------------------------------------------------- | | `AdminSessionHttpOperations` | `list`, `revoke`, `revokeAll` | `AdminSessionHttpApiLive` | Sessions, cookies, admin-session authorization | | `AdminPermissionDefinitionHttpOperations` | `create`, `get`, `list`, `update`, `disable`, `enable`, `delete` | `AdminPermissionDefinitionHttpApiLive` | Permission administration, sessions, cookies, app-owned permission-definition authorization | | `LoginNotificationHttpOperations` | `reportLogin` | None | No required feature service; login notifications are optional | | `SecurityTimelineHttpOperations` | `list` | `SecurityTimelineHttpApiLive` | Sessions, cookies, security-timeline store | | `AdminSecurityTimelineHttpOperations` | `list` | `AdminSecurityTimelineHttpApiLive` | Sessions, cookies, timeline store and admin authorization | | `TrustedDeviceHttpOperations` | `list`, `revoke` | `TrustedDeviceHttpApiLive` | Sessions, cookies, trusted-device store | | `AdminTrustedDeviceHttpOperations` | `list`, `revoke` | `AdminTrustedDeviceHttpApiLive` | Sessions, cookies, trusted-device store and admin authorization | ### Tokens and federation [#tokens-and-federation] | Service | Methods | Focused preset | Key required feature/domain services | | ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------- | --------------------------------------- | ---------------------------------------------------------------------------------------------------- | | `OAuthHttpOperations` | `authorizationStart`, `accountUnlink`, `linkConfirmationStart`, `linkConfirmationInspect`, `linkConfirmationConfirm` | `OAuthHttpApiLive` | OAuth providers/state, unlinking/link confirmation, OAuth HTTP config, sessions/cookies | | `OAuthProviderAuthorizationHttpOperations` | `authorize` | `OAuthProviderAuthorizationHttpApiLive` | OAuth provider authorization | | `OAuthTokenHttpOperations` | `token`, `introspect`, `revoke` | `OAuthTokenHttpApiLive` | Authorization-code grant and token HTTP config; other grants, introspection, and revocation optional | | `ApiKeyHttpOperations` | `create`, `list`, `revoke` | `ApiKeyHttpApiLive` | API-key management, sessions, cookies | | `RefreshTokenHttpOperations` | `refresh` | `RefreshTokenHttpApiLive` | Refresh-token management, JWT issuer, refresh-token HTTP config | | `JwtHttpOperations` | `introspect`, `revoke` | `JwtHttpApiLive` | JWT revocation and JWT HTTP config | | `JwtDiscoveryHttpOperations` | `jwks` | `JwtDiscoveryHttpApiLive` | JWKS provider | | `OidcDiscoveryHttpOperations` | `openidConfiguration` | `OidcDiscoveryHttpApiLive` | OIDC discovery metadata | ## Layer and boundary semantics [#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: ```ts import { PasswordHttpOperationsLive } from "@effect-auth/core/HttpApi/Password"; import type { Layer } from "effect"; type Requirements = L extends Layer.Layer ? R : never; type PasswordRequirements = Requirements; ``` 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.