Hono - Unkey Docs

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-honocd unkey-hono

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

Install the Unkey middleware#

npm install @unkey/hono

Add your root key#

Create a .env file:

.env

UNKEY_ROOT_KEY="unkey_..."

Note

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 authenticationapp.use(  "*",  unkey({    rootKey: process.env.UNKEY_ROOT_KEY!,  }),);// This route now requires a valid API keyapp.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 routeapp.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

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 middlewareapp.get("/", (c) => {  return c.json({ message: "Welcome! This route is public." });});// Protected routes, apply middleware to /api/* paths onlyapp.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.