Installation

npm install @unkey/hono

Quickstart

Here's a simple example of how to use the Unkey middleware in your Hono.js application:

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

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

app.use(
  "*",
  unkey({
    rootKey: process.env.UNKEY_ROOT_KEY!, // Your Unkey root key
  }),
);

app.get("/protected", (c) => {
  // Access the unkey response here to get metadata of the key etc
  const unkeyResponse = c.get("unkey");

  if (!unkeyResponse.data.valid) {
    return c.json({ error: "Unauthorized" }, 401);
  }

  return c.json({
    message: "Access granted!",
    keyId: unkeyResponse.data.keyId,
  });
});

Note: You need to provide your Unkey root key for key verification. Get your root key from the Unkey dashboard.

Configuration Options

The unkey middleware accepts the following configuration options:

Required Configuration

• rootKey: Your Unkey root key (required for API authentication)

Optional Configuration

• tags: Array of tags to filter keys during verification
• permissions: Required permissions for the key to be valid
• getKey: Custom function to extract the key from the request
• handleInvalidKey: Custom handler for invalid keys
• onError: Custom error handler

Advanced Usage

Custom Key Extraction

By default, the middleware looks for a bearer token in the Authorization header. You can customize this:

app.use(
  "*",
  unkey({
    rootKey: process.env.UNKEY_ROOT_KEY!,
    getKey: (c) => c.req.query("api_key"), // Get key from query parameter
  }),
);

Tags and Permissions

You can require specific tags or permissions for key verification:

app.use(
  "*",
  unkey({
    rootKey: process.env.UNKEY_ROOT_KEY!,
    tags: ["api", "production"],
    permissions: "read:data",
  }),
);

Custom Invalid Key Handler

Handle invalid keys with custom logic:

app.use(
  "*",
  unkey({
    rootKey: process.env.UNKEY_ROOT_KEY!,
    handleInvalidKey: (c, result) => {
      return c.json({ error: "Invalid API key" }, 401);
    },
  }),
);

Custom Error Handler

Handle API errors with custom logic:

app.use(
  "*",
  unkey({
    rootKey: process.env.UNKEY_ROOT_KEY!,
    onError: (c, err) => {
      console.error("Unkey error:", err.message);
      return c.json({ error: "Authentication service unavailable" }, 503);
    },
  }),
);

Documentation

Check out the full docs at unkey.com/docs/libraries/ts/hono.