Authentication
Peer REST authenticates callers with the X-Api-Key header when an API key is configured on the peer. Primary access control remains VPC-private — the listener is not exposed to the public internet.
Security model
| Layer | Role |
|---|---|
| VPC / firewall | Restricts port 3000 to internal ranges (e.g. 10.128.0.0/20) |
X-Api-Key | Optional application-layer secret when API_KEY is set on the peer |
X-Admin-Api-Key | Elevated key for admin token ops only (not the public contract focus) |
Keys are compared with a constant-time equality check. Do not put keys in query strings.
Sending the key
GET /api/tokens/stats HTTP/1.1
Host: <peer-internal-ip>:3000
X-Api-Key: <your-api-key>
curl -sS \
-H "X-Api-Key: $PEER_API_KEY" \
"http://<peer-internal-ip>:3000/api/tokens/stats"
When no key is configured
If API_KEY is unset on the peer, X-Api-Key is not required. VPC firewall rules alone gate access. Prefer configuring a key in production so compromised internal hosts cannot call the peer without a secret.
Admin routes
Admin wallet operations (distribute, top-up-reserve, reverse, audit-export, init) require X-Admin-Api-Key when ADMIN_API_KEY is set. Those routes are not the primary public contract — see Tokens for wallet ops and API reference for the full surface.
Common errors
| Status | Code | Meaning |
|---|---|---|
401 | UNAUTHORIZED | Missing X-Api-Key when a key is configured |
403 | FORBIDDEN | Key present but does not match |
503 | ADMIN_AUTH_UNAVAILABLE | Admin route called without ADMIN_API_KEY in production |
Full envelope shape: Errors.
Signed-in operators: mint and rotate ingestion API keys (and see operator auth detail) under Dashboard → Account → Developer API docs. This public page covers the Peer REST contract only.