Authentication

Every request to a /v1/* endpoint authenticates with one header: an API key sent as a bearer token. A recognized key returns 200 with the standard data + meta envelope:

curl -s https://astral-external-api-iksoi6t3nq-ue.a.run.app/v1/western/positions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"subject": {"datetime": "1990-05-15T14:30:00-04:00"}}' | jq

That single header is the entire model — no token endpoint, no refresh step, no expiring token to manage. Only the health probes GET /health and GET /ready are unauthenticated, so load balancers and uptime checks can reach them without a key.

Key format

Keys are prefixed by environment:

Prefix	Use
ak_test_	Development and evaluation
ak_live_	Production traffic

The prefix is safe to expose: in a log line, a config diff, or a secret-scanner rule you can tell which environment a key belongs to without revealing the rest of it. Log the prefix; never the full key.

Getting a key

The API is in early access, so keys are provisioned by hand. Request one through your Astral contact and you receive an ak_test_ key, plus an ak_live_ key when you are ready for production.

Upcoming

A self-serve dashboard for creating and revoking keys is planned. Until it ships, provisioning and revocation go through us.

Export your key so the examples across these docs can use it:

export API_KEY=ak_test_your_key_here

When authentication fails

Every auth failure returns 401 with an RFC 9457 problem body, and one of two codes says which failure it was. Branch on the code field, not the title text.

A request with no Authorization header returns auth.missing:

curl -s https://astral-external-api-iksoi6t3nq-ue.a.run.app/v1/western/positions \
  -H "Content-Type: application/json" \
  -d '{"subject": {"datetime": "1990-05-15T14:30:00-04:00"}}'

A key the API does not recognize — revoked, mistyped, or from the wrong environment — returns auth.invalid_key:

curl -s https://astral-external-api-iksoi6t3nq-ue.a.run.app/v1/western/positions \
  -H "Authorization: Bearer ak_test_not_a_real_key" \
  -H "Content-Type: application/json" \
  -d '{"subject": {"datetime": "1990-05-15T14:30:00-04:00"}}'

See Errors for the full catalog.

Rotating keys

An account can hold two active keys at once, so a replacement can be live before you retire the key it replaces — rotation never requires downtime.

1. Request a second key. Both keys now authenticate.
2. Deploy the new key to your services.
3. Confirm no requests are still arriving on the old key.
4. Revoke the old key.

Rotate on whatever schedule you set, and immediately if a key may have leaked. During early access, steps 1 and 4 go through your Astral contact.

Keeping keys secret

• Environment variables, not source code. Inject keys through your deployment environment or secret manager. A key committed to a repository is a key to rotate.
• Server-side only. Never ship a key in a browser bundle, a mobile app, or anything else running on hardware you don’t control — anyone can extract it. Route those clients through your own backend, which holds the key and calls the API.
• Log the prefix, not the key. The ak_test_ / ak_live_ prefix is safe in logs; the remainder is not.