GET STARTED · AUTHENTICATION

Authentication

Every request to api.hoonify.dev is authenticated with an API key passed as a bearer token. Keys are scoped, rotatable, and revocable without downtime — there is no in-band session state to invalidate.

Bearer token

Send the key in the Authorization header on every request:

shell

Authorization: Bearer hoon_sk_live_…

The OpenAI Python and TypeScript SDKs read it from OPENAI_API_KEY or theapiKey constructor option — either works as long as the value is a Hoonify key.

Key formats

Prefix	Environment	Notes
hoon_sk_live_	Production	Bills the org. Subject to rate limits and IP allowlist if configured.
hoon_sk_test_	Sandbox	Free, capped at 10K tokens/day per key. Returns deterministic mock outputs.
hoon_pk_live_	Public (browser)	Restricted — embed-only, requires referrer allowlist. Cannot create instances.

One-time reveal

Keys are revealed once at creation. Hoonify stores only a SHA-256 hash — if you lose a key you can't recover it, only rotate. The API keys page shows the prefix and last 4 characters for identification.

Scopes

Every key has an explicit scope set. Calls outside the scope return 403 forbidden_scope. Default for new keys is inference:write inference:read.

Scope	Grants
inference:write	Call /v1/chat/completions and /v1/embeddings.
inference:read	Read request metadata and usage records.
compute:write	Provision and terminate instances via /v1/instances.
compute:read	List and inspect instances. Read-only dashboards.
billing:read	Read invoices, credit balance, and usage rollups.
admin:write	Rotate keys, manage users, edit org settings. Admin keys only.

Rotation

Rotate a key from the API keys page. Rotation issues a new value and starts a 24-hour overlap window where both old and new keys validate. After the window, the old key fails closed with 401 unauthorized.

json

POST /v1/admin/keys/{key_id}/rotate
Authorization: Bearer hoon_sk_live_…   # admin:write required

{
  "overlap_seconds": 86400
}

Revocation

Revoke immediately via the API keys page or POST /v1/admin/keys/{key_id}/revoke. Revoked keys fail closed within ~5 seconds globally.

IP allowlist

Per-org IP allowlists are configured under Settings · Security. When set, keys are accepted only from listed CIDR ranges. Block actions return 403 ip_not_allowed with the offending source address.

Idempotent revoke

Revocation is idempotent — repeated calls return 200. Hoonify also emits a key.revoked webhook event so downstream services can purge cached credentials. See Webhooks.

Related: Rate limits · Webhooks