@unkey/hono
Hono.js middleware for authenticating API keys
## 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](https://app.unkey.com/settings/root-keys).
## 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:
```ts
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:
```ts
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:
```ts
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:
```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](https://unkey.com/docs/libraries/ts/hono).