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.