A minimal open platform for self-hosted services

CloudHub, GitNest and the other self-hosted services here recently needed to expose endpoints for scripts and phone shortcuts. Instead of giving every service its own auth, they share one gateway. This post is the minimal viable design.

Auth: bearer tokens are enough

Personal scale does not need OAuth. Static tokens over HTTPS are sufficient: generated server-side, issued per device, revocable at any time. The gateway validates the Authorization header centrally and every failure returns the same JSON shape.

curl -H "Authorization: Bearer $TOKEN" https://api.5457090.xyz/v1/ping
# 401 response
{"error":"unauthorized","code":40101,"message":"Missing or invalid API key","docs":"https://www.5457090.xyz/posts/openapi-guide.html"}

Error-code convention

error is a machine-readable lowercase word, code is five digits (HTTP status plus a two-digit sequence), message is for humans, docs points at this article. The common cases: 40101 unauthorized, 40400 endpoint not found, 40500 method not allowed.

Rate limiting and observability

A simple token bucket at the gateway; over-limit requests get 429 with a Retry-After header. Access logs rotate daily, and read-only /health and /metrics endpoints back the status pages, so monitoring scripts just pull JSON.

The whole thing is under two hundred lines, and the benefit is one consistent, inspectable, well-behaved API facade for every service on this network.