Skip to main content
The API service is the primary way users interact with Unkey. It exposes an authenticated RPC-style HTTP API for CRUD operations.

​
Request handling pipeline

Most endpoints share a standard middleware stack:
  • Panic recovery
  • Tracing
  • ClickHouse request metrics
  • Structured logging with request ID
  • Error translation using fault codes and OpenAPI error schemas
  • One-minute timeout
  • Request validation
Routes that serve internal tooling such as pprof use a reduced stack. The liveness and reference endpoints disable ClickHouse logging to avoid analytics noise.

​
Core services

The API service composes domain services into handlers during startup.
  • Authentication service for normalizing request credentials into principals. Protected handlers read the principal from the session and use it for permission checks.
  • Key service for root key verification, key authorization, and key mutations.
  • Rate limiting for standalone limits, key verification limits, and workspace API throttling.
  • Usage limiter backed by Redis counters and MySQL for credit tracking.
  • Audit log service for write actions.
  • Caches for key, API, and ratelimit namespace lookups.
  • Analytics connection manager for per-workspace ClickHouse access.

​
Data and storage

  • MySQL stores control plane data such as keys, APIs, identities, and permissions.
  • Redis stores regional counters and rate limiting state.
  • ClickHouse stores verification and analytics events.
ClickHouse is optional. When it is not configured, analytics writes become no-ops.

​
Cache invalidation

Each node maintains local caches with fresh/stale TTLs. Entries expire on their own schedule; there is no distributed invalidation.

​
Control plane and Vault integration

The API service uses Connect RPC clients to interact with:
  • Control plane deployment APIs for deployment operations.
  • Vault for analytics credentials and secret handling.
Clients inject Authorization: Bearer <token> headers on every request.

​
Reference and schema

The OpenAPI specification is bundled into the API service and served at /openapi.yaml. The /reference route serves the Scalar API reference UI built from the same spec.