API Keys

Bearer authentication

Every /v1 API call (except the public probes) authenticates with a bearer key:

Authorization: Bearer tk_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Keys come in two environments distinguished by prefix — tk_test_ and tk_live_ — followed by 43 characters of random material. Both run the same engine and return identical results; they differ in what they draw from: test keys share your account's one-time 250-request evaluation allowance (never billed, never resets), live keys use your plan's monthly quota. See Test vs Live Keys.

How keys are stored (and why we can't show them again)

We never store your key. At creation we keep a short lookup prefix and a one-way SHA-256 hash; verification is constant-time against the hash. This is why the full key is displayed exactly once — there is nothing on our side to re-reveal.

Authentication failures are uniform

A missing header, malformed key, unknown key, revoked key, or expired key all produce the identical unauthorized 401. The response never says which check failed — that's deliberate (it gives an attacker probing for valid keys nothing to work with).

After the key itself is accepted, two more checks can still reject the request:

• forbidden-ip 403 — the key is valid but presented from an IP outside your configured allowlist. Checked first.
• forbidden-scope 403 — the key lacks the scope the route requires.

Operational notes

• One key per system. You have 20 non-revoked key slots — use them so a single revocation never takes down an unrelated integration.
• Keys are independent of portal sessions. Portal session expiry never affects API traffic.
• No key can manage keys. Key creation and revocation happen only through the portal (or our support) — the keys:manage scope is reserved and never assignable, so a leaked API key cannot mint more keys.

Related

• Get an API Key — the portal flow
• Rotating Keys
• OAuth Client Credentials — the alternative for short-lived tokens