Authentication
One key, two headers, one rate limit.
Send the key
Either header works. Pick one and stop thinking about it.
curl https://v2.heppu.ai/api/v2/agents -H "x-api-key: hep_..."
# or
curl https://v2.heppu.ai/api/v2/agents -H "Authorization: Bearer hep_..."If both are present x-api-key wins.
Get a key
Profile, API keys in the dashboard. You need the apikey:manage capability, so owner or admin.
Keys are prefixed hep, expire after 30 days unless you set something else, and are shown once. Lose it, make a new one.
A key inherits the role of the user who made it. /v2 endpoints check that role. /v1 endpoints only check that the key is valid. If the key owner leaves the org, the key stops working the same minute.
Rate limit
1000 requests per key per 60 second sliding window. Same for everyone.
Over the limit you get 429 with headers X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset and Retry-After: 60, plus:
{
"error": {
"message": "Rate limit exceeded",
"code": "RATE_LIMITED",
"status": 429,
"retryInSeconds": 60,
"timestamp": "2026-09-11T10:00:00.000Z"
}
}One wrinkle
/v2 endpoints currently return a plain 401 instead of 429 when you are rate limited. If a working key suddenly 401s in a tight loop, that's why. Back off 60 seconds.
Sessions
/v2 endpoints also accept the dashboard's session cookie. Handy for calling the API from the browser while logged in. /v1 endpoints do not.
Don'ts
Don't put the key in a URL. Don't ship it in a browser bundle. Don't share one key across customers. Preflight (OPTIONS) answers with Access-Control-Allow-Origin: * but the real responses don't, so browser calls from a third party origin won't work anyway. The key is server-to-server: if your backend forwards a response to a browser, forward only the fields your UI needs rather than the raw body.