API keys
Create, scope and revoke keys for the Heizen API.
Open Developers → API keys and choose Create API key.
- Name the key after the system that will use it, such as "ATS sync".
- Pick the mode. Test keys (
hz_test_…) never use credits. Live keys (hz_live_…) work on real data. - Tick the scopes the integration needs and nothing more.
- Copy the key. This is the only time Heizen shows it in full; afterwards the list shows only the last four characters.
You can only grant scopes your own role holds.
Scopes
| Scope | Allows |
|---|---|
interviewers:read | List and read interviewers |
candidates:read | List and read candidates and invitations |
candidates:write | Create, update and delete candidates |
candidates:import | Import spreadsheets and read imports |
invitations:send | Create, bulk-create, resend, extend and cancel invitations |
results:read | Read sessions, transcripts, recordings, events and results |
results:export | Create and download exports |
developers:manage | Manage webhook endpoints and read events |
billing:read | Read credit usage |
GET /v1/ping and GET /v1/me work with any valid key.
Revoking and rotating
Revoke stops a key at once; requests with it get 401 invalid_api_key. To rotate without downtime, create the new key, deploy it, check Last used on the old key has stopped moving, then revoke the old one.
If a key leaks, revoke it first and investigate after.