Skip to main content
This Quickstart is currently in Beta. We’d love to hear your feedback!
Prerequisites:
  • Node.js 20 LTS or newer
  • npm 10+ or yarn 1.22+ or pnpm 8+
  • Optional: jq - for Auth0 CLI setup and openssl to generate secure secrets
  • Hono projects should use Hono >= 3.x (peer dependency)

​
Get Started

This quickstart shows the minimal, recommended way to secure a Hono application using @auth0/auth0-hono. It follows the repository’s recommended patterns: environment-driven configuration, app.use(auth(...)) middleware, and requiresAuth() for selective protection.
1

Create a new Hono application

Create a new Hono application using create-hono utility.
npm create hono@latest auth0-hono-app && cd auth0-hono-app
Select nodejs template
2

Install dependencies

Install the Auth0 middleware.
npm install @auth0/auth0-hono
This quickstart uses dotenv package to load environment variables from a .env file.To install dotenv locally:
npm install -D dotenv
Alterantively, if you prefer not to add a dependency, you can load an env file at process start using node’s --env-file flag, which lets you omit installing and importing dotenv.Modify the start script in package.json to:
  "scripts": {
    "start": "node --env-file=.env dist/index.js"
  }
3

Create an Auth0 application

Create an Auth0 Application in your Auth0 tenant (Regular Web Application) and record the Domain, Client ID, and Client Secret in environment variables to your project. You can choose to do this automatically by running a CLI command or do it manually via the Dashboard:
Run the following shell command on your project’s root directory to create an Auth0 app and generate a .env file:Use the generated .env or update values manually as needed.
4

Setup Hono web server with Auth0 middleware

Replace the initial template in index.ts file with the following example.
// index.ts
import 'dotenv/config'; // Not required if using --env-file flag
import { serve } from '@hono/node-server';
import { Hono } from 'hono';
import { auth, requiresAuth, Auth0Exception, type OIDCEnv } from '@auth0/auth0-hono';

const app = new Hono<OIDCEnv>();

// Configure auth middleware using environment variables.
app.use(
  auth({
    domain: process.env.AUTH0_DOMAIN,
    clientID: process.env.AUTH0_CLIENT_ID,
    clientSecret: process.env.AUTH0_CLIENT_SECRET,
    baseURL: process.env.BASE_URL,
    authRequired: false, // Make routes public by default, protect specific routes below
    session: {
      secret: process.env.AUTH0_SESSION_ENCRYPTION_KEY,
    },
  })
);

// Public route
app.get('/', (c) => c.text('Public — no login required'));

// Make most routes public, but protect /profile/*
app.use('/profile/*', requiresAuth());

app.get('/profile', async (c) => {
  const session = await c.var.auth0Client?.getSession(c);
  const user = session?.user;
  return c.json({ message: 'Protected profile', user });
});

const port = Number(process.env.PORT) || 3000;
serve({ fetch: app.fetch, port }, (info) => {
    console.log(`Server is running on http://localhost:${info.port}`);
  }
);
5

Run your app

Start the server and open http://localhost:3000.
npm run dev
CheckpointYour Hono app should be running on http://localhost:3000. The / route is public. Visiting /profile should redirect you to login (if not authenticated) and then return profile data after successful authentication.

​
Troubleshooting

Cause: The callback URL configured in the Auth0 Dashboard does not exactly match BASE_URL + the callback route (e.g., http://localhost:3000/auth/callback).Fix:
  1. Verify .env BASE_URL value.
  2. Ensure Allowed Callback URLs in Auth0 Dashboard contain http://localhost:3000/auth/callback.
  3. Restart dev server after changes.
Cause: AUTH0_SESSION_ENCRYPTION_KEY is missing or too short, or you changed it while cookies from an old secret remain.Fix:
  • Ensure AUTH0_SESSION_ENCRYPTION_KEY is at least 32 characters.
  • Clear browser cookies for localhost after changing the key.
  • Restart dev server.
Cause: Middleware not installed or placed after route registration.Fix:
  • Ensure app.use(auth(...)) runs before routes that depend on authentication.
  • Confirm package installed: npm ls @auth0/auth0-hono.
Cause: Deployment platform not providing environment variables or using different names.Fix:
  • Map environment variables in your hosting provider dashboard to the names used in this quickstart.
  • For Cloudflare Workers, verify session/cookie handling is compatible with the platform.

​
Advanced Usage

  • Selective protection: use app.use(auth({ authRequired: false })) to make routes public by default and app.use('/private/*', requiresAuth()) to protect specific paths.
  • Silent login: use attemptSilentLogin() middleware to try silent authentication for better UX.
  • Custom login flow: call login({...}) to customize forwarded query params, redirectAfterLogin, or silent login options.
  • Token management: the middleware exposes access and ID tokens via the session; follow least-privilege for scopes and rotate refresh tokens safely.

​
Best Practices & Security

  • Keep secrets out of source control — use environment variables.
  • Use a 32+ character AUTH0_SESSION_ENCRYPTION_KEY.
  • Set cookie secure to true in production and set appropriate sameSite policy.
  • Limit token scopes; use audience only when requesting access tokens for APIs.
  • Catch Auth0Exception in app.onError to handle auth-specific errors cleanly.