> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hexclave.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Ship Production-Ready Auth

> Lock down page and API access, handle secrets and environments, then align domains, OAuth, email, webhooks, and dashboard production mode with Hexclave.

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](/guides/other/tutorials/build-a-saas-with-hexclave) first. For team RBAC before launch, see [Build a team-based app](/guides/other/tutorials/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)

You typically combine **one or more** of:

1. **Middleware** — cheap gate when the URL alone tells you the area is private (for example everything under `/app`).
2. **Server Components / server loaders** — `await hexclaveServerApp.getUser({ or: "redirect" })` (or handle `null`) on the route that renders sensitive UI.
3. **Client Components** — `useUser({ or: "redirect" })` for UX; **never** the only layer for authorization.

<Tabs>
  <Tab title="Middleware (route prefix)">
    ```tsx title="middleware.ts" theme={null}
    import { NextRequest, NextResponse } from "next/server";
    import { hexclaveServerApp } from "@/stack/server";

    export async function middleware(request: NextRequest) {
      const user = await hexclaveServerApp.getUser();
      if (!user) {
        return NextResponse.redirect(new URL("/handler/sign-in", request.url));
      }
      return NextResponse.next();
    }

    export const config = {
      matcher: "/app/:path*",
    };
    ```

    Match **only** prefixes that should be gated. Do **not** blanket-match `/` or you can block static assets and Stack’s **`/handler`** routes (sign-in, sign-up, callbacks).

    If your project uses hosted components or cross-domain auth, prefer protecting pages with `hexclaveServerApp.getUser({ or: "redirect" })` in a Server Component. Middleware cannot run the runtime `redirectToSignIn()` helper, so only hard-code `/handler/sign-in` here when your app owns a same-domain handler route.
  </Tab>

  <Tab title="Server Component">
    ```tsx title="app/app/dashboard/page.tsx" theme={null}
    import { hexclaveServerApp } from "@/stack/server";

    export default async function DashboardPage() {
      await hexclaveServerApp.getUser({ or: "redirect" });
      return <h1>Dashboard</h1>;
    }
    ```
  </Tab>

  <Tab title="Client Component (UX gate)">
    ```tsx title="app/app/settings/client-gate.tsx" theme={null}
    "use client";

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

    export function SettingsGate({ children }: { children: React.ReactNode }) {
      useUser({ or: "redirect" });
      return <>{children}</>;
    }
    ```
  </Tab>
</Tabs>

### `redirect` vs `throw`

* **`{ or: "redirect" }`** — use when a browser navigation is appropriate (pages, most Server Components).
* **`{ or: "throw" }`** — use in **server actions**, **route handlers**, and other places where redirecting would be wrong; map errors to `401`/`403` responses yourself.

```tsx title="app/api/me/route.ts" theme={null}
import { hexclaveServerApp } from "@/stack/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 Next.js composition

Authentication prevents **impersonation**, but **HTML composition** still matters:

* **Client Components** ship to the browser; gating with hooks does not hide their bundled code.
* **Server Components**: a protected parent does **not** guarantee an unprotected child (or an unprotected segment under a layout) never reaches the client. Anything that embeds **secrets or PII** should **itself** call `getUser({ or: "redirect" })` / `getUser({ or: "throw" })` (or otherwise avoid rendering that data when unauthenticated).
* **Middleware**: on **Next.js 15.2.3+**, middleware-only protection does not leak unprotected server-rendered fragments the way older versions could; still treat **authorization** (who may perform an action) as a **server** concern.

Read the full discussion in [User fundamentals — Protecting a page](/guides/getting-started/user-fundamentals#protecting-a-page).

<Info>
  Treat **client-side** checks as **UX only**. Anything that mutates data or exposes another customer’s data must be enforced on the server (Server Components, server actions, route handlers, or your backend with the **secret server key** or validated tokens). For team-scoped apps, re-check [RBAC](/guides/apps/rbac/overview) on the server, not only with `usePermission`.
</Info>

## 2. Secrets, keys, and environments

<Warning>
  **`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](/sdk/objects/hexclave-app) and the [REST API overview](/api/overview).
</Warning>

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.

<Steps>
  <Step title="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](/guides/apps/launch-checklist/overview#domains).
  </Step>

  <Step title="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](/guides/apps/launch-checklist/overview#oauth-providers) and [Auth providers](/guides/apps/authentication/auth-providers).
  </Step>

  <Step title="Email">
    Point outbound mail at **your** SMTP/domain so magic links and invitations come from a domain users trust. Details: [Launch checklist — Email server](/guides/apps/launch-checklist/overview#email-server) and [Emails](/guides/apps/emails/overview).
  </Step>

  <Step title="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](/guides/apps/launch-checklist/overview#enabling-production-mode)).
  </Step>
</Steps>

## 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](/guides/apps/webhooks/overview).

## 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.

## Related guides

| Topic                            | Guide                                                                            |
| -------------------------------- | -------------------------------------------------------------------------------- |
| First integration                | [Build a SaaS with Hexclave](/guides/other/tutorials/build-a-saas-with-hexclave) |
| Page protection details          | [User fundamentals](/guides/getting-started/user-fundamentals)                   |
| Domains, OAuth, email, prod mode | [Launch checklist](/guides/apps/launch-checklist/overview)                       |
| `HexclaveServerApp` and keys     | [HexclaveApp SDK reference](/sdk/objects/hexclave-app)                           |
| Webhook verification             | [Webhooks](/guides/apps/webhooks/overview)                                       |
| REST from your backend           | [API overview](/api/overview)                                                    |

## FAQ

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="Should production and development share one Stack project?">
    Prefer **separate projects** (or strictly separated keys and OAuth clients) so you never point production OAuth callbacks at localhost, and so a leaked dev key cannot touch production data.
  </Accordion>

  <Accordion title="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](/guides/other/tutorials/build-a-team-based-app).
  </Accordion>
</AccordionGroup>