Create an API key, send it as a bearer token, and keep it out of your client code.
The API authenticates with a workspace API key sent as a bearer token.
Create a key
Go to Settings → Developer and create a key. You must be the workspace owner, and the workspace must be on Scale or above.
A key looks like:
hs_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxThe key is shown once, at creation. We store only a hash of it, so we cannot show it to you again — copy it then. If you lose it, revoke it and create another.
Send it
Pass it in the Authorization header on every request:
curl https://www.hey.support/api/v1/me \
-H 'Authorization: Bearer hs_live_…'GET /me is the cheapest way to check a key works — it returns the workspace the key belongs to.
Scope
A key is scoped to the workspace that created it, not to a single agent. It can read and write every resource in that workspace, so treat it as a full credential.
Requests for resources in any other workspace return 404.
Rate limits
Limits are per key, per hour. Once a key is accepted, every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset — successes included, not only the request that gets refused — so you can pace a job instead of waiting to be told no. Read Remaining as you go rather than counting requests yourself. (A rejected key returns 401 with no rate headers, since there is no key to report on.)
Going over returns 429. See Errors for the ceiling and the retry advice.
Keep it server-side
An API key is a secret. Never ship one in browser JavaScript, a mobile app, or anything else a user can read — anyone holding it has your workspace's data.
If you need to put the chat widget on a page, that is the embed script, which needs no key at all.
Revoking
Revoke a key from Settings → Developer. Revocation takes effect immediately, and any request using it then gets a 401.
Revoke and replace if a key is ever pasted into a shared document, a ticket, a log, or a repository.
If your plan changes
API access is a Scale feature. Dropping below Scale does not delete your keys, but requests start returning 403 — including any Zapier automations, which run on this same API. Upgrading restores them without you re-creating anything.