API
This document only covers v2 of the Unkey API. The v1 API on Cloudflare Workers is deprecated and will be removed in the future. It was too hard to selfhost anyways.
Our API runs on AWS containers, in multiple regions behind a global load balancer to ensure high availability and low latency.
The source code is available on GitHub.
Quickstart
To get started, you need go1.24+ installed on your machine.
Configuration
The API server requires a json configuration file to be passed as an argument to the binary.
You can use ${SOME_NAME} as placeholder in your config file and it will be replaced by the value of the environment variable SOME_NAME.
The most up to date json schema can be found here: https://raw.githubusercontent.com/unkeyed/unkey/refs/heads/main/go/schema.json
Most IDEs support JSON schema validation if you put it in your config file.
You can check out our own configuration files on GitHub.
General Configuration
These settings define the fundamental properties of the server.
platformstring
The platform this server is running on ("aws", "gcp", ...).
Most metrics include this information to help with troubleshooting and monitoring.
imagestring
The container image and version identifier for this instance.
httpPortnumber
The HTTP port where the server will listen for incoming connections. Defaults to 7070.
regionstring
Geographic region identifier where this server is deployed (e.g., "us-west-1")
Heartbeat Configuration
The API can send heartbeats to a destination to monitor its health.
heartbeatobject
Configuration for server health check reporting. Contains the following properties:
urlRequiredstring
Endpoint URL where heartbeat signals will be sent (e.g., "http://monitor.example.com/heartbeat")
intervalRequirednumber
Time between heartbeat signals in seconds (e.g., 30 for checking every half minute)
Cluster Configuration
Settings for cluster operation when running multiple server instances together.
clusterobject
Settings for multi-server cluster operations:
nodeIdstring
Unique identifier for this node in the cluster (e.g., "node-1", "server-east-1")
If omitted, a random id will be generated.
advertiseAddrstring
Network address other nodes will use to contact this node (e.g., "10.0.0.1", "node1.example.com")
rpcPortstring
Port used for internal cluster communication via RPC. Defaults to "7071".
gossipPortstring
Port used for cluster membership and state dissemination. Defaults to "7072".
discoveryobject
Configuration for how cluster nodes discover each other on startup.
Only one discovery method can be configured at a time.
staticobject
Fixed list of cluster nodes for stable environments:
addrsRequiredstring[]
List of node addresses to connect to (e.g., ["node1:7071", "node2:7071"])
redisobject
Redis-based dynamic discovery for flexible environments. All nodes will send heartbeats to the Redis server with their address.
urlRequiredstring
Redis connection string (e.g., "redis://redis.example.com:6379")
Logging and Monitoring
Configuration for observability and debugging capabilities.
logsobject
Logging configuration settings:
colorboolean
Enable colored output in log messages for better readability
Database Configuration
Database connection settings for the server's data storage.
databaseRequiredobject
Database connection configuration:
primaryRequiredstring
Primary database connection string for read and write operations (e.g., "postgresql://user:pass@localhost:5432/dbname")
readonlyReplicastring
Optional read-only database replica for scaling read operations
ClickHouse Configuration
clickhouseobject
ClickHouse integration for metrics and logging:
urlRequiredstring
ClickHouse server connection string (e.g., "http://clickhouse:8123")
Last updated on