Authentication

All requests (except /healthz, /readyz, /v1/meta/* and the OpenAPI spec at /v1/docs) require a bearer token.

Authorization: Bearer YOUR_API_KEY

Replace YOUR_API_KEY with the key from your dashboard. Live keys start with dv_live_.

Key types

Create keys from your dashboard → API Keys. You can create, label, rotate, and revoke keys independently. Each key is scoped to its owning account — all usage counts toward the account's plan quota.

IP allowlisting

For dv_live_* keys, you can restrict calls to a list of IPs or CIDR ranges. Requests from outside the list return 403 with error code ip_not_allowed. An empty list means no restriction. The check uses the real client IP even though the API sits behind Cloudflare.

203.0.113.10/32       # specific IP
198.51.100.0/24       # range

Set allowed IPs from dashboard → API Keys → edit.

Best practices

1. Generate separate keys per environment — prod, staging, CI, local.
2. Use IP allowlisting on prod keys. Compromise blast radius = zero if your servers are the only IPs that work.
3. Never embed dv_live_* keys in mobile apps, web bundles, or public GitHub repos.
4. Rotate regularly — create a new key, switch your servers over, then revoke the old one. Both keys work during the switch, so rotation is zero-downtime.
5. Use environment variables — never hardcode keys.

WWW-Authenticate challenge

If you send a missing/invalid token, the response is 401 Unauthorized with:

WWW-Authenticate: Bearer realm="LifeAstroAPI"

Dashboard sessions vs. API keys

The website dashboard signs you in with Firebase (Google or email/password) and calls /v1/auth/* and /v1/dashboard/* with a short-lived Firebase ID token. Those tokens and dv_live_* keys are not interchangeable — ID tokens cannot call compute endpoints, and API keys cannot access dashboard routes. Your integration only ever needs the API key.