Bun

What you’ll build

A Bun HTTP server that requires a valid API key on every request. Invalid or missing keys get rejected with a 401. Time to complete: ~3 minutes

Prerequisites

Unkey account (free)
Keyspace created in your Unkey dashboard
Bun installed

Want to skip ahead?

Clone the complete example and run it locally.

Create a new Bun project

mkdir unkey-bun && cd unkey-bun
bun init -y

Install the SDK

bun add @unkey/api

Add your root key

Create a .env file with your credentials from the Unkey dashboard:

.env

UNKEY_ROOT_KEY="unkey_..."

Create your server

Replace the contents of index.ts:

index.ts

import { Unkey } from "@unkey/api";

const unkey = new Unkey({ rootKey: Bun.env.UNKEY_ROOT_KEY! });

const server = Bun.serve({
  async fetch(req) {
    // 1. Extract the key from the Authorization header
    const key = req.headers.get("Authorization")?.replace("Bearer ", "");

    if (!key) {
      return Response.json({ error: "Missing API key" }, { status: 401 });
    }

    // 2. Verify with Unkey
    try {
      const { data } = await unkey.keys.verifyKey({ key });

      if (!data.valid) {
        // Key is invalid, expired, rate limited, etc.
        return Response.json(
          { error: "Invalid API key", code: data.code },
          { status: 401 },
        );
      }

      // 3. Key is valid, return your response
      return Response.json({
        message: "Hello from protected endpoint!",
        keyId: data.keyId,
        identity: data.identity,
      });
    } catch (err) {
      console.error(err);
      return Response.json({ error: "Verification failed" }, { status: 500 });
    }
  },
  port: 3000,
});

console.log(`Server running at http://localhost:${server.port}`);

Run your server

bun run index.ts

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 endpoint!",
  "keyId": "key_...",
  "identity": null
}

Try without a key:

Test without key

curl http://localhost:3000

You’ll get:

{
  "error": "Missing API key"
}

What’s in `data`?

After successful verification:

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[]?`	Permissions attached to the key
`permissions`	`string[]?`	Permissions attached to the key
`identity`	`object?`	Identity info if `externalId` was set when creating the key
`ratelimits`	`object[]?`	Rate limit states (if rate limiting configured)

Adding routes

Bun’s built-in server uses a single fetch handler. For multiple routes, pattern match on the URL:

index.ts

import { Unkey } from "@unkey/api";

const unkey = new Unkey({ rootKey: Bun.env.UNKEY_ROOT_KEY! });

// Helper to verify key
async function authenticate(req: Request) {
  const key = req.headers.get("Authorization")?.replace("Bearer ", "");
  if (!key) return { valid: false, error: "Missing API key" };

  try {
    const { data } = await unkey.keys.verifyKey({ key });
    return data;
  } catch (err) {
    console.error(err);
    return { valid: false, error: "Verification failed" };
  }
}

const server = Bun.serve({
  async fetch(req) {
    const url = new URL(req.url);

    // Public route
    if (url.pathname === "/") {
      return Response.json({ message: "Welcome! Try /api/secret" });
    }

    // Protected routes
    if (url.pathname.startsWith("/api/")) {
      const auth = await authenticate(req);

      if (!auth.valid) {
        return Response.json(
          { error: auth.error || "Unauthorized" },
          { status: 401 },
        );
      }

      // Route to specific handlers
      if (url.pathname === "/api/secret") {
        return Response.json({ secret: "data", keyId: auth.keyId });
      }

      if (url.pathname === "/api/user") {
        return Response.json({ user: auth.identity });
      }
    }

    return Response.json({ error: "Not found" }, { status: 404 });
  },
  port: 3000,
});

Next steps

Add rate limiting

Protect endpoints from abuse

Set usage limits

Cap total requests per key

Add permissions

Fine-grained access control

SDK Reference

Full TypeScript SDK docs

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 (note the space)

Environment variables not loading?

Bun automatically loads .env files. Make sure: - The .env file is in your project root - You’re using Bun.env.VAR_NAME not process.env.VAR_NAME - Restart the server after changing .env

TypeScript errors?

Run bun init -y to ensure you have a proper tsconfig.json. Bun handles TypeScript natively, no extra setup needed.

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 new Bun project

Install the SDK

Add your root key

Create your server

Run your server

Test it

What’s in `data`?

Adding routes

Next steps

Add rate limiting

Set usage limits

Add permissions

SDK Reference

Troubleshooting

​What you’ll build

​Prerequisites

Want to skip ahead?

Create a new Bun project

Install the SDK

Add your root key

Create your server

Run your server

Test it

​What’s in data?

​Adding routes

​Next steps

Add rate limiting

Set usage limits

Add permissions

SDK Reference

​Troubleshooting

What you’ll build

Prerequisites

What’s in `data`?

Adding routes

Next steps

Troubleshooting