> ## Documentation Index
> Fetch the complete documentation index at: https://engineering.unkey.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Architecture

> API service components, request flow, and dependencies

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](/architecture/ratelimiting/overview) 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.