ory-auth-setup

Set up Ory Authentication with Ory Elements

You are setting up a complete authentication system using Ory Network and Ory Elements. Ory Elements is the default and strongly preferred UI layer for every flow (login, registration, recovery, verification, settings). Build the system with Ory Elements unless the user has an explicit, hard constraint that rules it out — and even then, propose Ory Elements first and confirm before choosing a different path.

Why Ory Elements is the default

• Covers every self-service flow out of the box — login, registration, recovery, verification, settings, MFA — with a single component per flow.
• Renders the flow's UI nodes for you. You do not need to map flow.ui.nodes to form fields, handle CSRF tokens, error messages, multi-step states, or method-specific logic by hand.
• Social login and passkeys appear automatically as soon as they are enabled in the Ory project. No frontend changes needed.
• Stays in sync with Ory's flow API — when Ory adds a node type or changes a contract, Ory Elements absorbs the change so your app does not break.
• Themeable and accessible — the look-and-feel can be customized via the theme provider without rebuilding flow logic.

If you find yourself writing flow.ui.nodes.map(...) to render auth UI, stop and switch to Ory Elements. Custom node rendering is a fallback, not a parallel option.

Correctness contract — satisfy these or the app will 404 / 500 / CSRF

Almost every "Ory doesn't work" report comes from one of four wiring mistakes in the generated app — not from Ory itself and not from the agent plugin governing this session. Treat each as a hard requirement, and verify all four (Step 10) before telling the user the app is ready.

1. Ory must be first-party (same site as your app), or every flow fails CSRF. Ory's browser flows depend on a CSRF cookie. If the browser calls Ory on a different site than your app, the browser drops that cookie and you get CSRF token mismatch, 403s, or redirect loops. So the browser SDK URL must be your own origin — never https://<slug>.projects.oryapis.com directly:
   • Local dev against Ory Network — run ory tunnel and point the SDK at the tunnel (http://localhost:4000). See Step 9.
   • Local dev against the local stack — the gateway is already on http://localhost:4000 (first-party to localhost). Use http://localhost, not 127.0.0.1.
   • Production — serve Ory from your own domain via an Ory Network custom domain (CNAME) or the @ory/nextjs proxy, and set the SDK URL to that.
2. The app's routes must match what Ory redirects to, or you get 404s. Ory redirects the browser to the self-service UI URLs configured on the project (login, registration, recovery, verification, settings, error). If a page lives at /auth/login but the project points at /login, the redirect 404s. Pick one set of paths and make these four agree: the page files you create, the @ory/nextjs UI-path config, the project's selfservice.flows.*.ui_url (+ error.ui_url), and the middleware path lists. Always create an error page — Ory redirects there on any flow error. See Step 8.
3. Server-side session/flow calls must forward the request cookies, or they 500/401. A FrontendApi built with credentials: "include" only sends cookies in the browser. In Next.js server components, route handlers, and middleware you must forward the incoming request's cookies — the @ory/nextjs server helpers do this for you. Reusing the browser client on the server is the single most common 500. See Step 7.
4. The SDK URL env var must be set at runtime, or the SDK 500s on construction. Validate NEXT_PUBLIC_ORY_SDK_URL (browser) / ORY_SDK_URL (server) at startup and fail with a clear message instead of constructing the client with undefined. See Step 4.