unkey

Unkey API Key & Rate Limiting Skill

Overview

Unkey is high-performance infrastructure for minting, revoking, validating API keys, and enforcing distributed rate limits at the edge with global sub-10ms response times.

Installation

npm install @unkey/api @unkey/ratelimit

Verifying an Inbound API Key

import { verifyKey } from '@unkey/api';

export async function authenticateApiKey(apiKeyValue: string) {
  const { result, error } = await verifyKey({
    key: apiKeyValue,
    apiId: process.env.UNKEY_API_ID!,
  });

  if (error) {
    console.error('Unkey verification failed:', error);
    return { authenticated: false };
  }

  if (!result.valid) {
    return { authenticated: false, reason: result.code };
  }

  return {
    authenticated: true,
    ownerId: result.ownerId,
    meta: result.meta,
  };
}

Creating a New Customer API Key

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

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

const created = await unkey.keys.create({
  apiId: process.env.UNKEY_API_ID!,
  prefix: 'acme',
  ownerId: 'user_9921',
  name: 'Production Worker Key',
  ratelimit: {
    type: 'fast',
    limit: 100,
    duration: 60000, // 100 requests per minute
  },
  meta: {
    tier: 'enterprise',
  },
});

console.log('Customer API Key:', created.result?.key);

AI Pitfalls & Anti-Hallucination Guidelines

• Plaintext Key Security: The plaintext API key is only returned once upon creation. Store hash or instruct user to copy immediately.
• Root Key vs Client Verification: Key creation requires UNKEY_ROOT_KEY. Verification only requires apiId.

Production Verification Checklist

• API keys verified on edge runtime before handler execution
• Rate limit exhaustion returns HTTP 429 Too Many Requests
• Key prefixes utilized to simplify customer debugging (e.g. pk_live_...)

---

Last Verified: 2026-07-03