Skip to main content

​
Overview

The UserTrace API uses long-lived API keys for programmatic access from a script, a CI job, or your agent’s production runtime, where a short-lived dashboard session is impractical. A key grants exactly its owner’s access: the same organization, the same scoped environments. Creating a key never widens what someone can see.

​
Base URL

​
Creating a key

Keys are created in the dashboard.
1

Open the Agent Setup page and scroll to the bottom

The API key panel is the last section on the page.
2

Click Create API Key

Give it a name that says where it runs, such as CI reporting or prod-agent, so you know what you’re revoking later.
3

Copy the key immediately

The full key is shown exactly once. Only a hash is stored, so it cannot be recovered afterwards.
If you lose a key, you cannot look it up. Revoke it and create another.
The panel lists every key with its prefix, when it was created, when it was last used, and its status. Revoke takes effect on the very next request.
Maximum 10 active keys. Revoked keys stay in the list as history and don’t count toward the limit.
“Last used” lags by up to an hour. It’s written at most once per hour to keep the write off the request path, and stays empty until the key’s first use, so a key you just used may still show —.

​
Using a key

Pass it in the x-usertrace-api-key header. No Authorization header is needed.

​
What a key can access

Keys work only on endpoints that explicitly opt in: Every other endpoint rejects a key with 401, including the API-key management endpoints themselves, so a leaked key cannot mint more keys.

​
Rate limits

120 requests per minute, per key. Exceeding it returns 429 with a Retry-After header giving the seconds until the window resets:
The window is fixed rather than sliding, so a burst spanning a minute boundary can briefly reach twice the limit. Dashboard-authenticated requests are not rate limited.

​
Errors