Ship Production-Ready Auth

Going live is not only “turning on production mode.” This guide focuses on what must be true so only signed-in users reach protected surfaces, secrets stay server-only, and Stack’s dev-friendly defaults are replaced with your domains, OAuth apps, and email. If you are still wiring Stack into your app, complete Build a SaaS with Hexclave first. For team RBAC before launch, see Build a team-based app.

What you will have at the end

A clear model for protecting pages, layouts, route handlers, and server actions—and when to use middleware vs in-render checks.
Awareness of Next.js + sensitive HTML so you do not leak data through composition.
A secrets and environment split that keeps the server key out of the browser.
A launch-aligned checklist (domains, OAuth, email, production mode) with pointers to deeper docs.
A webhook verification mindset (signed payloads only).

1. Protect a page (and know what that actually guarantees)

Use useUser({ or: "redirect" }) in a Client Component. This lets Hexclave capture the current browser URL and establish the PKCE handoff before navigating to hosted authentication.

app/app/dashboard/page.tsx

"use client";

import { useUser } from "@hexclave/next";

export default function DashboardPage() {
  const user = useUser({ or: "redirect" });
  return <h1>Welcome, {user.displayName ?? user.primaryEmail ?? user.id}</h1>;
}

This is a navigation and UX gate, not authorization for sensitive operations. Enforce those checks again in the server action, route handler, or backend that reads or mutates protected data.

`redirect` vs `throw`

{ or: "redirect" } — use with useUser. The getUser overload is deprecated on both client and server app objects because app type describes permissions, not whether the call runs in a browser.
{ or: "throw" } — use in server actions, route handlers, and other places where navigation is not the server code’s responsibility; map errors to 401/403 responses yourself.

app/api/me/route.ts

import { hexclaveServerApp } from "@/hexclave/server";
import { NextResponse } from "next/server";

export async function GET() {
  try {
    const user = await hexclaveServerApp.getUser({ or: "throw" });
    return NextResponse.json({ id: user.id });
  } catch {
    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
  }
}

Sensitive content and client-side rendering

Client Components ship to the browser. Gating one with useUser controls navigation, but does not hide its bundled code or authorize protected backend operations. Keep secrets out of client code and enforce access in the server action, route handler, or backend serving the data. Read the full discussion in User fundamentals — Protecting a page.

Treat client-side checks as UX only. Anything that mutates data or exposes another customer’s data must be enforced in server actions, route handlers, or your backend with the secret server key or validated tokens. For team-scoped apps, re-check RBAC on the server, not only with usePermission.

2. Secrets, keys, and environments

HEXCLAVE_SECRET_SERVER_KEY (or ssk_...) must only exist in server-side environments (SSR, route handlers, server actions, your backend). Never prefix it with NEXT_PUBLIC_, never import it from code that runs in the browser, and never log it. See the HexclaveApp SDK reference and the REST API overview.

Practical split:

Variable	Typical exposure	Use
`NEXT_PUBLIC_HEXCLAVE_PROJECT_ID`	Browser + server	Identifies the project to the hosted UI and client SDK.
`NEXT_PUBLIC_HEXCLAVE_PUBLISHABLE_CLIENT_KEY` (if used)	Browser + server	Client-safe key where your project uses publishable keys.
`HEXCLAVE_SECRET_SERVER_KEY`	Server only	Elevated server SDK and REST server API.

Use separate Stack projects or at least separate env values for production vs staging when possible. Rotate keys from the dashboard if a secret is exposed.

3. Domains, OAuth, email, and production mode

Stack’s dev defaults (localhost callbacks, shared OAuth keys, shared mail) are convenient but not what you want for real users.

Domains and callbacks

Add your real https://… origin under Domain & Handlers and disable Allow all localhost callbacks when you no longer need local redirects against production configuration. Details: Launch checklist — Domains.

OAuth providers

Create your own OAuth clients per provider, set the provider callback URLs Stack documents, then paste your client ID and secret in the dashboard (leave shared keys for local dev only). Details: Launch checklist — OAuth providers and Auth providers.

Point outbound mail at your SMTP/domain so magic links and invitations come from a domain users trust. Details: Launch checklist — Email server and Emails.

Enable production mode

After the above, turn on production mode in Project Settings so dashboard guardrails match how you run in prod (Launch checklist — Enabling production mode).

4. Webhooks

If you consume Stack webhooks, verify every payload (for example with Svix and STACK_WEBHOOK_SECRET) before acting on events—treat unsigned or failed verification as 400. Implementation patterns: Webhooks.

5. Before you flip traffic

Smoke-test sign-in, sign-up, password reset, and OAuth on the production domain after DNS and env vars are final.
Confirm redirect URLs in third-party consoles (OAuth, IdP) match the Stack callback URLs you use in prod.
Align session / cookie behavior with your hosting (same-site, HTTPS, reverse proxies) per your platform docs.
Plan rollback: keep prior env values or a maintenance window note so you can revert dashboard or env changes quickly.

Topic	Guide
First integration	Build a SaaS with Hexclave
Page protection details	User fundamentals
Domains, OAuth, email, prod mode	Launch checklist
`HexclaveServerApp` and keys	HexclaveApp SDK reference
Webhook verification	Webhooks
REST from your backend	API overview

FAQ

Is middleware enough to protect my API?

Middleware runs on matching routes and is great for coarse “must be logged in” gates. Route handlers and server actions should still call getUser({ or: "throw" }) (or equivalent) and return proper HTTP errors—middleware will not run for every internal call path, and authorization (what that user may do) belongs next to your business logic.

Where do teams and RBAC fit for launch?

Model permissions in the dashboard, then enforce them on the server for every sensitive operation. Walkthrough: Build a team-based app.

Getting Started

Going Further

Apps

Integrations

Other

What you will have at the end

1. Protect a page (and know what that actually guarantees)

`redirect` vs `throw`

Sensitive content and client-side rendering

2. Secrets, keys, and environments

3. Domains, OAuth, email, and production mode

4. Webhooks

5. Before you flip traffic

FAQ

​What you will have at the end

​1. Protect a page (and know what that actually guarantees)

​redirect vs throw

​Sensitive content and client-side rendering

​2. Secrets, keys, and environments

​3. Domains, OAuth, email, and production mode

​4. Webhooks

​5. Before you flip traffic

​Related guides

​FAQ

What you will have at the end

1. Protect a page (and know what that actually guarantees)

`redirect` vs `throw`

Sensitive content and client-side rendering

2. Secrets, keys, and environments

3. Domains, OAuth, email, and production mode

4. Webhooks

5. Before you flip traffic

Related guides

FAQ