Send the key
Put the key in the Authorization header as Bearer aik_live_…. Keys in a query string are never accepted, so they don't end up in logs.
Create and manage keys
Keys are managed in the dashboard under Integrations → API keys by company admins and organization owners and admins. Keys work on the free trial too, within its interview minutes, and on every paid plan.
- Shown once. The secret appears only when the key is created or rotated. We store a hash of it, so it can't be shown again.
- Expiry. 30 days, 90 days (the default), 1 year, a date up to 2 years ahead, or never. The list warns 7 days before a key expires; an expired key can be extended.
- Rotate. Makes a new key with the same name, permissions and IP rules. The old key keeps working for 24 hours (its expiry moves there, unless it ends sooner), so you can deploy the new one first; revoke it sooner from its page. The new key keeps the same expiry date (an already expired key's replacement gets 90 days).
- Without downtime. Rotate, deploy the new key within the 24 hours, then revoke the old one or let it expire. Idempotency keys work across your keys, so a retry sent with the new key never creates twice.
- Revoke. Every request with the key fails from then on. Revoking can't be undone.
- Within 30 seconds. A revoke or an edit of permissions, IPs or expiry applies within 30 seconds. A key stops working at its expiry time, never later.
Permissions
Every operation needs exactly one permission (scope). Give each key only the ones its system uses.
| Scope | Allows |
|---|---|
interviews:read | List published interviews |
candidates:read | Read candidates |
candidates:write | Create candidates |
candidates:delete | Erase candidates and all their data |
invitations:read | Read invitations and their status |
invitations:write | Create, revoke and resend invitations |
results:read | Read session status, scores and coverage |
exports:read | Download PDF reports and CSV exports |
webhooks:manage | Add, change and remove webhook endpoints (Webhooks) |
A request without the operation's permission gets 403 with This API key lacks the "<scope>" permission.
IP allowlist
A key can be limited to up to 50 IP addresses or CIDR ranges (IPv4 and IPv6). From any other address it gets 403 with This API key can't be used from this IP address. An empty list allows any IP.
When a key is refused
| Status | Message | Why |
|---|---|---|
401 | Missing or malformed API key. | No Bearer aik_live_… header |
401 | Invalid or revoked API key. | Unknown or revoked key, or a key sent to another data region's host: a key works only on its company's region (api.testee.ai for the EU, api.us.testee.ai for the US) |
401 | This API key expired on <date>. Create a new key or extend it in Integrations. | The key's expiry passed (the date in UTC) |
403 | This API key lacks the "<scope>" permission. | The operation needs another scope |
403 | This API key can't be used from this IP address. | Outside the key's IP allowlist |