Hono

This guide walks you through to implement Aura Auth in a Hono application to a complete support. If you haven't configured Aura Auth yet, start with the Installation Guide and Quick Start Guide to set up your Auth instance and environment variables. Then follow the steps in this guide to integrate Aura Auth with your Hono application.

Aura Auth is working on developing a Hono-specific package that will provide additional utilities for Hono applications. For now, the core package can be used to implement authentication in Hono with the patterns outlined in this guide. Stay tuned for updates on the Hono package!

Setup Aura Auth

Create an Auth Instance

Create an auth.ts file in src/lib directory to configure your Aura Auth instance.

src/lib/auth.ts

import { createAuth } from "@aura-stack/auth"

export const auth = createAuth({
  oauth: ["github"],
  basePath: "/api/auth",
})

export const { handlers, api, jose } = auth

The basePath should match the path where your auth route handlers are mounted and baseURL should point to your local development server or deployed application URL.

Mount HTTP Handlers

Mount the Aura Auth handlers using a wildcard route under your /api/auth subpath. Hono passes the native Web Standard Request object through c.req.raw, so the handler can delegate directly.

src/index.ts

import { Hono } from "hono"
import { handlers } from "@/lib/auth"

const app = new Hono()

app.all("/api/auth/*", async (ctx) => {
  return await handlers.ALL(ctx.req.raw)
})

export default app

Usage

Middleware

Middleware is a powerful way to protect your routes and access session data across your app. Create a with-auth.ts file in src/middlewares.

src/middlewares/with-auth.ts

import { api } from "@/lib/auth"
import { createMiddleware } from "hono/factory"
import type { Session } from "@aura-stack/auth"

/**
 * Type definition for Hono's Context Variables to include the session.
 */
export type AuthVariables = {
  session: Session | null
}

export const withAuth = createMiddleware<{ Variables: AuthVariables }>(async (ctx, next) => {
  try {
    const session = await api.getSession({
      headers: ctx.req.raw.headers,
    })
    if (!session.authenticated) {
      return ctx.json({ error: "Unauthorized", message: "Active session required." }, 401)
    }
    ctx.set("session", session.session)
    return await next()
  } catch {
    return ctx.json({ error: "Unauthorized", message: "Active session required." }, 401)
  }
})

The plugin returns session data only when the request is authenticated, which keeps downstream routes simple and predictable.

Get Session

Use the middleware in your app and protect routes by checking for an active session before allowing access.

src/index.ts

import { Hono } from "hono"
import { handlers } from "@/lib/auth"
import { type AuthVariables, withAuth } from "@/middlewares/with-auth"

const app = new Hono<{ Variables: AuthVariables }>()

app.get("/", (ctx) => {
  return ctx.text("Welcome to the Aura Auth Hono App!")
})

app.all("/api/auth/*", async (ctx) => {
  return await handlers.ALL(ctx.req.raw)
})

app.get("/api/protected", withAuth, (ctx) => {
  const session = ctx.get("session")
  return ctx.json({
    message: "You have access to this protected resource.",
    session,
  })
})

export default app

This pattern works well for dashboards, account endpoints, and any route that should not return private data unless the request is authenticated.

Common Pitfalls

Keep basePath aligned with your auth route. If your auth endpoint is /api/auth/*, the auth config should use basePath: "/api/auth".
Import the middleware from the correct folder. The shared middleware lives in src/middlewares/with-auth.ts.
Use session.authenticated as the guard. Check that flag before exposing private data.
Keep the auth handler and route logic separate. The auth route should only forward requests to Aura Auth.