Authentication
Two credentials, for two different jobs. An API key sends traffic. Your account session manages the account. Neither can do the other's job, and that is deliberate.
Which credential goes where
| Endpoint | Credential |
|---|---|
GET /v1/models |
API key |
POST /v1/chat/completions |
API key |
POST /v1/api-keys |
Account session |
GET /v1/api-keys |
Account session |
GET /v1/api-keys/{key_public_id} |
Account session |
POST /v1/api-keys/{key_public_id}/rotate |
Account session |
DELETE /v1/api-keys/{key_public_id} |
Account session |
GET /v1/usage |
Account session |
GET /v1/usage/summary |
Account session |
GET /v1/usage/by-model |
Account session |
GET /v1/usage/by-api-key |
Account session |
GET /v1/billing/balance |
Account session |
GET /v1/billing/transactions |
Account session |
GET /v1/billing/invoices |
Account session |
GET /v1/billing/invoices/{number} |
Account session |
GET /v1/billing/funding |
Account session |
ak- key to a session endpoint returns
401 — deliberately, not as a side effect. If one leaked key could
list, mint and revoke the others, the compromise of a single credential would
become the compromise of every credential on the account.
Sending an API key
Authorization: Bearer $ASTRODYNE_API_KEY
Keys look like ak-…. Create them in the
console or through the
API keys API.
Sending an account session
Authorization: Bearer $ASTRODYNE_SESSION_TOKEN
The same session the console uses — from the astrodyne_token
cookie, or as a Bearer token. This is what the API keys, usage and billing
endpoints expect.
Authentication is not permission
A valid credential proves who you are. Whether your account may use
the API is a separate question, answered by your
invite status. A valid key on an account
without access returns 403 beta_access_required, and no key will
change that.
Handling keys safely
- The full key is shown once, at creation or rotation. Astrodyne stores only a one-way hash and can never show it again.
- Store keys in environment variables or a secrets manager — never in source control.
- Call the API from your server. Do not ship a key in production browser or mobile code, where anyone can read it.
- Revoke the moment you suspect exposure, in the
console or with
DELETE /v1/api-keys/{key_public_id}. A revoked key stops authenticating immediately. - To replace a secret without losing usage history, rotate rather than revoke and recreate — the key id stays the same.
Optional key settings
A key can carry a spending limit, an expiry, and a model allow/block list. An
expired key returns 401 expired_api_key; a key over its spending
limit returns 429 spending_limit_exceeded; a key barred from a
model returns 403 model_not_allowed.
Authentication failures
| HTTP | code | When |
|---|---|---|
| 401 | authentication_error | No credential was presented, or the wrong kind was. |
| 401 | invalid_api_key | The key is not recognised. |
| 401 | expired_api_key | The key passed its expiry. |