Authentication

API keys, environments, and rate limits.

Every request needs an API key in the Authorization header:

curl https://api.hooper.gg/v1/balance \
  -H "Authorization: Bearer hk_prod_8KzQ…"

Keys are issued by Hooper for your organization. The plaintext is shown once when it’s created; Hooper stores only a hash and cannot recover it. Keep it server-side — never ship it in a browser or mobile app.

Key format

Prefix	Meaning
hk_prod_…	API key for production (api.hooper.gg)
hk_stg_…	API key for staging
hws_prod_… / hws_stg_…	Webhook signing secret (see Webhooks)

The middle segment names the environment that issued the credential. A production server refuses a staging key with a specific error so the mismatch is obvious:

{ "error": { "type": "authentication_error", "code": "wrong_environment",
             "message": "This key was minted for the 'stg' environment; this server accepts 'prod' keys" } }

Error codes

HTTP	code	Meaning
401	missing_api_key	No Authorization: Bearer header
401	invalid_api_key	Malformed, unknown, or revoked key
401	wrong_environment	Key belongs to the other environment
429	rate_limit_exceeded	More than 60 requests/minute on this key — honour Retry-After

Rotating a key

Ask Hooper to mint a new key, switch your integration to it, then have the old one revoked. Revocation is immediate; a revoked key returns invalid_api_key.