انتقل إلى المحتوى

API

Authentication.

Every request carries a company API key as a bearer token. Each key has its own permissions, optional IP allowlist and expiry.

آخر تحديث 19 نوفمبر 2026

وثائق المطورين متاحة باللغة الإنجليزية فقط.

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.

curl "https://api.testee.ai/v1/interviews?limit=1" \  -H "Authorization: Bearer $TESTEE_API_KEY"

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.

ScopeAllows
interviews:readList published interviews
candidates:readRead candidates
candidates:writeCreate candidates
candidates:deleteErase candidates and all their data
invitations:readRead invitations and their status
invitations:writeCreate, revoke and resend invitations
results:readRead session status, scores and coverage
exports:readDownload PDF reports and CSV exports
webhooks:manageAdd, 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

StatusMessageWhy
401Missing or malformed API key.No Bearer aik_live_… header
401Invalid 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)
401This API key expired on <date>. Create a new key or extend it in Integrations.The key's expiry passed (the date in UTC)
403This API key lacks the "<scope>" permission.The operation needs another scope
403This API key can't be used from this IP address.Outside the key's IP allowlist