Authentication

Every /v1 request carries an API key. There is no other authentication scheme.

Sending a key

Send it as a bearer token. This is the form every example in these docs uses and the one you should prefer.

Authorization header

curl https://api.example.com/v1/codes/101076 \
  -H "Authorization: Bearer hcapi_live_…"

If a bearer token is awkward in your client, the same key is accepted on an X-API-Key header. Never put a key in a query string: URLs are logged by proxies, browsers and error trackers, and a key in one is a key you have to rotate.

Alternative

curl https://api.example.com/v1/codes/101076 \
  -H "X-API-Key: hcapi_live_…"

What a key looks like

Keys begin with hcapi_live_ followed by 32 random characters. Test keys, where issued, begin with hcapi_test_. The prefix is ours — a key never carries another organisation's name.

How keys are stored

We store a SHA-256 hash of the key and the first few characters for display. The full key is shown once, at creation, and cannot be recovered afterwards — not by you and not by us. If you lose one, create another and revoke the old one.

Keys are secrets. Keep them server-side. A key in browser JavaScript or a mobile binary is a key that has been published.

Revoking

Revoke a key from the dashboard. Revocation takes effect immediately; anything still using that key starts receiving 401 invalid_api_key. Create and deploy the replacement first.

When authentication fails

Status	Code	Meaning
`401`	invalid_api_key	No key was sent, or the key is unknown or revoked.
`403`	endpoint_not_available_on_plan	The key is valid; the plan does not include this.
`429`	rate_limit_exceeded	Too many requests this minute.
`429`	monthly_quota_exceeded	The monthly allowance is used up.