Simple Unkey API

A simple TypeScript API that returns random data with Unkey authentication.

Features

• 🔐 Unkey API key authentication
• 📊 Random data generation (users, products, quotes, jokes)
• ⚡ Fast and lightweight
• 🛠️ TypeScript with strict type checking
• 📝 Code style enforced with Biome

Requirements

• Node.js 22+ (the repo pins pnpm 11 via packageManager, which needs a modern Node)
• pnpm (corepack enable will pick up the pinned version)

Setup

1. Install dependencies

pnpm install

2. Configure environment variables

Copy .env.example to .env and add your Unkey credentials:

cp .env.example .env

Update the .env file with your actual Unkey credentials:

• MY_ROOT_KEY: Your Unkey root key (get it from https://unkey.com)
• UNKEY_API_URL (optional): Base URL of the Unkey API. Defaults to https://api.unkey.com. Set this to test against a local or staging deployment — e.g. http://localhost:7070 for the local Tilt stack (unkey/api:dev), whose dashboard runs at http://localhost:3000.

The root key must belong to whichever deployment UNKEY_API_URL points at — a production root key will not verify against a local instance, and vice versa. The server prints its target on startup.

3. Run the development server

pnpm dev

The server will start on http://localhost:8080 (or the PORT specified in .env).

Note: if something else on your machine already owns port 8080 (Tilt, for example), the server will still report "Server running on port 8080" while requests to localhost:8080 go to the other process. Set PORT to a free port to avoid this.

4. Verify it works

curl http://localhost:8080/health
curl -H "Authorization: Bearer <a key from your Unkey API>" http://localhost:8080/api/me

/api/me returns what Unkey reported for the key, which makes it a quick way to confirm a deployment is talking to the right API and root key.

Docker

Build the Docker image

docker build -t simple-unkey-api .

Run the container

docker run -p 8080:8080 \
  -e MY_ROOT_KEY=your_unkey_root_key_here \
  simple-unkey-api

Or using a .env file:

docker run -p 8080:8080 --env-file .env simple-unkey-api

API Endpoints

Public Endpoints

• GET / - API information and available endpoints
• GET /health - Health check endpoint

Protected Endpoints (require Unkey API key)

All endpoints under /api/* require a valid Unkey API key in the Authorization header.

• GET /api/users?count=5 - Get random users
• GET /api/products?count=5 - Get random products
• GET /api/quotes?count=1 - Get random quotes
• GET /api/jokes?count=1 - Get random jokes
• GET /api/random - Get a random item of any type
• GET /api/me - Echo Unkey's verification result for the calling key (keyId, name, credits, permissions)

Authentication

Include your Unkey API key in the Authorization header:

curl -H "Authorization: Bearer your_api_key_here" http://localhost:8080/api/users

Keys are checked against POST https://api.unkey.com/v2/keys.verifyKey using the MY_ROOT_KEY root key. Responses you may get back:

Status	Meaning
200	Key verified, request served
401	Missing header, or Unkey reported the key as invalid (the reason field carries Unkey's code, e.g. NOT_FOUND, EXPIRED, RATE_LIMITED, USAGE_EXCEEDED, DISABLED)
500	MY_ROOT_KEY is not set on the server
502	Unkey was unreachable or rejected the root key (the details field carries Unkey's message)

Examples

Get 10 random users

curl -H "Authorization: Bearer your_api_key_here" http://localhost:8080/api/users?count=10

Get 5 random products

curl -H "Authorization: Bearer your_api_key_here" http://localhost:8080/api/products?count=5

Get a random quote

curl -H "Authorization: Bearer your_api_key_here" http://localhost:8080/api/quotes

Get random jokes

curl -H "Authorization: Bearer your_api_key_here" http://localhost:8080/api/jokes?count=3

Development

Build for production

pnpm build

Start production server

pnpm start

Lint code

pnpm lint

Auto-fix linting issues

pnpm lint:fix

Tech Stack

• TypeScript
• Express.js
• Unkey for authentication
• Biome for linting and formatting
• pnpm for package management