Hono

What you’ll build

A Hono app with API key authentication using the @unkey/hono middleware. All routes (or specific ones) require a valid API key. Time to complete: ~5 minutes

Prerequisites

Unkey account (free)
Keyspace created in your Unkey dashboard
Node.js 18+ or Bun

Want to skip ahead?

Clone the complete example and run it locally.

Create a Hono app

npm create hono@latest unkey-hono
cd unkey-hono

pnpm create hono@latest unkey-hono
cd unkey-hono

bun create hono@latest unkey-hono
cd unkey-hono

Choose your preferred runtime (Node.js, Bun, Cloudflare Workers, etc.)

Install the Unkey middleware

npm install @unkey/hono

pnpm add @unkey/hono

bun add @unkey/hono

Add your root key

Create a .env file:

.env

UNKEY_ROOT_KEY="unkey_..."

The Hono middleware verifies keys directly against your root key.

Add the middleware

Update src/index.ts:

src/index.ts

import { Hono } from "hono";
import { unkey, UnkeyContext } from "@unkey/hono";

// Type the context so you get autocomplete for c.get("unkey")
const app = new Hono<{ Variables: { unkey: UnkeyContext } }>();

// Protect all routes with API key authentication
app.use(
  "*",
  unkey({
    rootKey: process.env.UNKEY_ROOT_KEY!,
  }),
);

// This route now requires a valid API key
app.get("/", (c) => {
  // Access verification result from context
  const keyInfo = c.get("unkey");

  return c.json({
    message: "Hello from protected route!",
    keyId: keyInfo.keyId,
    valid: keyInfo.valid,
  });
});

// Another protected route
app.get("/secret", (c) => {
  const keyInfo = c.get("unkey");

  return c.json({
    secret: "data",
    identity: keyInfo.identity,
    meta: keyInfo.meta,
  });
});

export default app;

Run your app

npm run dev

pnpm dev

bun run dev

Test it

Create a test key in your Unkey dashboard, then:

Test with valid key

curl http://localhost:3000 \
  -H "Authorization: Bearer YOUR_API_KEY"

You should see:

{
  "message": "Hello from protected route!",
  "keyId": "key_...",
  "valid": true
}

Without a key, you’ll get a 401:

Test without key

curl http://localhost:3000

{
  "error": "Unauthorized"
}

Protecting specific routes

Instead of protecting all routes, you can apply the middleware to specific paths:

src/index.ts

import { Hono } from "hono";
import { unkey, UnkeyContext } from "@unkey/hono";

const app = new Hono<{ Variables: { unkey: UnkeyContext } }>();

// Public route, no middleware
app.get("/", (c) => {
  return c.json({ message: "Welcome! This route is public." });
});

// Protected routes, apply middleware to /api/* paths only
app.use("/api/*", unkey({ rootKey: process.env.UNKEY_ROOT_KEY! }));

app.get("/api/secret", (c) => {
  const keyInfo = c.get("unkey");
  return c.json({ secret: "data", keyId: keyInfo.keyId });
});

app.get("/api/user", (c) => {
  const keyInfo = c.get("unkey");
  return c.json({ identity: keyInfo.identity });
});

export default app;

What’s in the context?

After verification, c.get("unkey") contains:

Field	Type	Description
`valid`	`boolean`	Whether the key passed all checks
`code`	`string`	Status code (`VALID`, `NOT_FOUND`, `RATE_LIMITED`, etc.)
`keyId`	`string`	The key’s unique identifier
`name`	`string?`	Human-readable name of the key
`meta`	`object?`	Custom metadata associated with the key
`expires`	`number?`	Unix timestamp (in milliseconds) when the key will expire. (if set)
`credits`	`number?`	Remaining uses (if usage limits set)
`enabled`	`boolean`	Whether the key is enabled
`roles`	`string[]?`	Named role(s) assigned to the key, each representing a set of permissions
`permissions`	`string[]?`	List of individual permissions granted to the key
`identity`	`object?`	Identity info if `externalId` was set when creating the key
`ratelimits`	`object[]?`	Rate limit states (if rate limiting configured)

Middleware options

unkey({
  rootKey: process.env.UNKEY_ROOT_KEY!, // Required: Your root key

  // Optional: Custom error handling
  onError: (c, error) => {
    console.error("Unkey error:", error);
    return c.json({ error: "Auth service unavailable" }, 503);
  },

  // Optional: Custom unauthorized response
  handleInvalidKey: (c, result) => {
    return c.json(
      {
        error: "Invalid API key",
        code: result.code,
      },
      401,
    );
  },
});

Next steps

Add rate limiting

Limit requests per key

Set usage limits

Cap total requests per key

Add permissions

Fine-grained access control

Hono SDK Reference

Full middleware documentation

Troubleshooting

Getting 401 even with a valid key?

Ensure the key hasn’t expired or been revoked - Verify the header format: Authorization: Bearer YOUR_KEY

Environment variables not loading?

For Node.js: Install dotenv and add import 'dotenv/config' at the top - For Bun: .env is loaded automatically - For Cloudflare Workers: Use wrangler secret or wrangler.toml

Deploying to Cloudflare Workers?

Use wrangler secrets for your root key:

npx wrangler secret put UNKEY_ROOT_KEY

Then access it from your Hono bindings. Add UNKEY_ROOT_KEY to your Bindings type and read it via ctx.env.UNKEY_ROOT_KEY or env.UNKEY_ROOT_KEY in your handlers.

Getting Started

Platform

Build & Deploy

Networking

Observability

CLI

Security

Keyspaces

AI Code Gen

Audit Logs

CLI

Errors

What you’ll build

Prerequisites

Want to skip ahead?

Create a Hono app

Install the Unkey middleware

Add your root key

Add the middleware

Run your app

Test it

Protecting specific routes

What’s in the context?

Middleware options

Next steps

Add rate limiting

Set usage limits

Add permissions

Hono SDK Reference

Troubleshooting

​What you’ll build

​Prerequisites

Want to skip ahead?

Create a Hono app

Install the Unkey middleware

Add your root key

Add the middleware

Run your app

Test it

​Protecting specific routes

​What’s in the context?

​Middleware options

​Next steps

Add rate limiting

Set usage limits

Add permissions

Hono SDK Reference

​Troubleshooting

What you’ll build

Prerequisites

Protecting specific routes

What’s in the context?

Middleware options

Next steps

Troubleshooting