API keys and limits
Scopes, expiry, rotation, revoking, per-key limits and what is logged.
Scopes
| Scope | Tools the key can call |
|---|---|
free | Free tools only |
free+ask | Free tools and ask (ask and ask_result) |
Start with free. A free+ask key can start research-assistant runs that spend AI budget, so give it only to a machine you trust and make it expire.
Make a key
Under Account, Connect your agent: a name (the machine or tool it is for), a scope, and an expiry of 30, 90, 365 days or none. The key starts with hek_, is shown once, and only a
hash of it is stored: nobody, including the owner, can read it back. Any approved account can make keys.
Expiry
An expired key stops working the moment it expires: the server answers 401 with the date. It stays in your list, marked expired, until you revoke it, and it still counts toward the 10 active keys.
Rotate and revoke
- Press Rotate on the key. A new key is made with the same name, scope and length of life, and shown once.
- The old key keeps working, so nothing breaks while you move your clients to the new one. Update
HARNESSLAB_API_KEYand restart the clients. - Test the new key with Test my key. Then press Revoke on the old key. Revoking is immediate and cannot be undone.
Rotate on a schedule that suits you, and at once if a key may have leaked. An expiry is the same habit made automatic.
Limits
These are the defaults. The owner of a deployment can change the three per-key limits in the app, so the numbers for your key are the ones Test my key shows.
| Limit | Default | What happens past it |
|---|---|---|
| Calls a minute, per key | 60 | HTTP 429 with Retry-After; any request counts, including tools/list. |
| Tool calls a month, per key | 1,000 | HTTP 429 until 00:00 UTC on the first of next month. Retry-After says how many seconds. |
| Output tokens a day, per key | 200,000 (about 4 characters each) | HTTP 429 until 00:00 UTC. Retry-After says how many seconds. |
| Results in one reply | 10 hits; 3,000 tokens by default, at most 12,000 | What does not fit is left out and a line says how to narrow. |
| Active keys per person | 10 | Making or rotating another key is refused until you revoke one. |
| ask spend, per key a day | $5 (plus your account's own daily caps) | ask is refused with the reset time; max_cost_usd caps one question. |
Rate-limit headers
Every reply carries the per-minute limit in the headers of the IETF draft for rate limits, so a client can slow down before it is refused:
q is the quota, w the window in seconds, r the calls left, t the seconds until the oldest call leaves the window
RateLimit-Policy: "minute";q=60;w=60
RateLimit: "minute";r=42;t=17A 429 adds Retry-After: the seconds to wait. A reply never carries your key.
What is logged
For each tool call the server keeps the tool name, the time, how many tokens it returned, how long it took, whether it worked, and the first 200 characters of the query, topic or claim id, with anything that looks like a secret cut out.
For ask and ask_result it keeps nothing of the question. The log is kept for 30 days, then deleted. Per day it also keeps a count of calls and tokens for each key.
The key itself is never logged and never stored; only its hash is. The owner of the service sees each key's name, owner, prefix and use, not the key.
Test my key
Under Account, Connect your agent paste a key to see whether it is valid, revoked, expired or the wrong scope; which tools it can call and which it cannot; its limits; and what it used today. It only looks at your own keys. Pasting someone else’s key, or one that does not exist, gives the same answer: no such key on your account.