---
title: Hono
description: SSR auth for Hono with HttpOnly cookie sessions — one middleware is the whole server surface.
sidebar:
  icon: flame
  order: 5
---

`@vortex-api/convex-auth/hono` is the Hono server adapter. Sessions live in app-origin HttpOnly cookies; a middleware lands OAuth/magic-link redirects, refreshes sessions near expiry, and serves the intent-based `/api/auth` proxy. It implements the [SSR auth contract](/convex-auth/ssr-contract).

Because Hono is fetch-shaped, the same adapter works on `@hono/node-server`, Bun, Deno, and Workers-style runtimes.

A working example lives in `examples/hono`.

## Install

```bash
pnpm add @vortex-api/convex-auth hono
```

Point the server at your Convex deployment and wire the backend (component mount, `convex/auth.ts`, `convex/http.ts`) per [Installation](/convex-auth/installation):

```bash
echo 'CONVEX_URL=https://<your-deployment>.convex.cloud' >> .env.local
```

Hono serves the server surface — middleware, the `/api/auth` proxy, and session helpers. Your sign-in UI lives wherever your frontend does (a SPA hitting the proxy, Hono-rendered pages, or a mobile app); it calls the same [React client](/convex-auth/react) or plain `fetch` against `/api/auth`.

## Middleware

Register `convexAuthMiddleware` once at the app level:

```ts
// src/index.ts
import { Hono } from "hono";
import { convexAuthMiddleware } from "@vortex-api/convex-auth/hono";
import { api } from "../convex/_generated/api";

const app = new Hono();
app.use("*", convexAuthMiddleware({ actions: api.auth }));
```

The middleware intercepts `POST /api/auth` itself and the boundary pass covers every other request — no separate route wiring is needed.

### Options

| Option                   | Default                                                     | Description                                                                                                                                                             |
| ------------------------ | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `actions`                | required                                                    | The `api.auth` object re-exporting `convexAuth` actions.                                                                                                                |
| `convexUrl`              | `CONVEX_URL` → `VITE_CONVEX_URL` → `NEXT_PUBLIC_CONVEX_URL` | Convex deployment URL.                                                                                                                                                  |
| `apiRoute`               | `/api/auth`                                                 | Path that proxies auth actions.                                                                                                                                         |
| `cookieConfig.maxAge`    | `null` (session cookie)                                     | Cookie lifetime in seconds. Must be `null` or a positive number.                                                                                                        |
| `requireLandingVerifier` | `true`                                                      | Require OAuth/magic-link landings to carry a verifier param matching the cookie minted at flow start. Set `false` only for deployments that predate verifier threading. |
| `verbose`                | `false`                                                     | Debug logging.                                                                                                                                                          |

## Session helpers

All helpers take the Hono context; only `getConvexAuthSession` and `getAuthServerState` call Convex — the cookie helpers are local reads:

```ts
import {
  getConvexAuthSession,
  getConvexAuthToken,
  convexAuthCookieState,
  getAuthServerState,
} from "@vortex-api/convex-auth/hono";

app.get("/me", async (c) => {
  const session = await getConvexAuthSession(c, { actions: api.auth });
  if (session === null) return c.json({ error: "Unauthorized" }, 401);
  return c.json(session.user);
});
```

| Helper                  | Verifies with Convex? | Use for                                                    |
| ----------------------- | --------------------- | ---------------------------------------------------------- |
| `getConvexAuthSession`  | yes (`verifySession`) | Route guards — revoked sessions resolve `null`.            |
| `getConvexAuthToken`    | no                    | The raw JWT for `ConvexHttpClient.setAuth` / `fetchQuery`. |
| `convexAuthCookieState` | no                    | Cheap UX guards — expiry from JWT claims only.             |
| `getAuthServerState`    | yes                   | The seed shape `ConvexAuthProvider`'s `serverState` wants. |

Helpers see the post-boundary session: when the middleware rotated tokens mid-request, they resolve the fresh tokens, not the stale cookie.

## Standalone proxy route

Prefer owning the route file instead of the middleware intercept:

```ts
import { convexAuthProxyHandler } from "@vortex-api/convex-auth/hono";

app.post("/api/auth", convexAuthProxyHandler({ actions: api.auth }));
```

## Convex wiring

The backend is the standard consumer setup — component mount in `convex/convex.config.ts`, `convexAuth({...})` in `convex/auth.ts`, `auth.addHttpRoutes(http)` in `convex/http.ts`. See [Installation](/convex-auth/installation).

## Example apps

- **`examples/hono`** — the packaged adapter demo: `convexAuthMiddleware`, the `/api/auth` proxy, and `getConvexAuthSession` against a real Hono app.

  ```bash
  cd examples/hono
  pnpm install
  pnpm run dev
  ```

- **`examples/server`** — the same Hono shape in token mode using `ConvexHttpClient` directly. The reference for servers that do not need cookie sessions (scripting, CLIs, service-to-service).

  ```bash
  cd examples/server
  pnpm install
  pnpm run dev
  ```

## Next steps

**[SSR auth contract](/convex-auth/ssr-contract)**

The boundary semantics every SSR adapter implements.

**[React hooks](/convex-auth/react)**

The client your SPA uses against the Hono proxy.

**[Production](/convex-auth/production)**

Deploy, monitor, and rotate.

**[Example source](https://github.com/VortexNYC/convex-auth/tree/main/examples/hono)**

`examples/hono` and `examples/server` on GitHub.