API keys and deployment

Authenticate the oo-workers API with email/password or bearer API keys, mint and revoke keys, and expose the dashboard safely behind TLS.

Authentication#

Every /api/* endpoint requires auth. There are two ways in:

  • Dashboard: email and password. The first visit runs a setup wizard to create the admin account; after login the server keeps an HttpOnly session cookie.
  • Programmatic (CLI, agents, CI): an API key sent as Authorization: Bearer oo_….

The only intentionally public surfaces are GET /status/<slug> (the status pages you curate) and POST /heartbeat/:token (where your cron jobs ping). Everything else returns 401 without a valid key or session.

API keys#

In the dashboard, open Settings → API keys and click New key, then copy it from the one-time panel. Or from the shell:

docker compose exec worker bun scripts/create-api-key.ts --name ci
# prints oo_<...>  (copy it now; it is not shown again)

Only a hash is stored. Create as many keys as you want with different names, and revoke any of them individually from the same page; revocation takes effect immediately.

Expose to the network#

The UI port binds to 127.0.0.1 by default, so only your own machine reaches it. To put it online:

TLS overlay (recommended). Point DNS at the host, set OO_DOMAIN=monitor.example.com in .env, then:

docker compose -f docker-compose.yml -f docker-compose.tls.yml up -d

Caddy fetches a Let's Encrypt certificate automatically and serves the UI over HTTPS on :443. Both ports must be reachable from the public internet: 80 for the Let's Encrypt ACME HTTP-01 challenge, 443 to serve HTTPS.

Bring your own proxy. Set OO_BIND_ADDR=0.0.0.0 and put Traefik, nginx, or Tailscale Funnel in front. Plain HTTP on a public IP is not a good idea.

A note on trust#

An authenticated caller can ask the worker to probe any host and port it can reach, including your internal network. That is intentional: self-hosted monitoring is meant to watch private services like a NAS, internal dashboards, or staging APIs. Only hand out keys to people you would already trust with that access.

Was this page helpful?