Installation

``bash
npm install @unkey/hono
`

Quickstart

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

`ts
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:

$3

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

$3

- 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

$3

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

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

$3

You can require specific tags or permissions for key verification:

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

$3

Handle invalid keys with custom logic:

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

$3

Handle API errors with custom logic:

`ts
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.