Authentication

Every endpoint under /v1 needs a key. Create one under Keys in the dashboard, then present it as a bearer token. An x-api-key header is accepted as well, for clients that cannot set Authorization. /health is open.

• Scoped to an organization. Credits, usage and keys all belong to the organization, not to a person.
• Prefixed hohe_. A key without the prefix is rejected as invalid_api_key before any lookup happens.
• Stored as a hash. The plaintext is shown once at creation and exists nowhere in our systems, so we cannot recover a lost key. Lose one and the fix is to revoke it in the dashboard and create another.
• Revocable. Every request looks the key up afresh with no cache, so a disabled key stops working on the next request.
• Rate limited per key, using limits stored on the key itself. See Rate limits.

Whether a key is valid and whether the account can pay are different questions, and they fail with different statuses on purpose: 401 for the key, 402 for the balance. A client that rotates keys on every 4xx would do the wrong thing for an empty balance, and one that tops up on every 4xx would do the wrong thing for a revoked key.

GET /v1/models and GET /v1/usage need a valid key but not a balance, so an account that has run out of credits can still see prices and read its usage.

• missing_api_key: no Authorization and no x-api-key header.
• invalid_api_key: not recognised, or no hohe_ prefix.
• api_key_revoked: the key was disabled.
• api_key_expired: the key's expiry has passed.

All four are HTTP 401. The full list is in Errors.