Managing API keys

Open API keys in TraceFast →

API keys are managed in the TraceFast app under Settings → API keys. A secret is shown once, when the key is created, and is never stored in a form anyone can read back. This page follows the cabinet screen by screen; how a key is sent with a request is on API keys.

The API part of Settings has three tabs — API keys, Usage and Audit log — next to Account, Connected apps and Billing.

Who can create keys

Keys come with a paid plan. On a plan without API access the screen says The API is not included in your plan and offers no Create API key button.

Each plan allows a set number of keys at once — see pricing. A strip at the top of the screen names your plan and whether it includes the API, how many of the plan's keys are in use, the request rate (per key or shared across the plan, as the plan sets it), the APIs the plan opens and a link to Compare plans →. At the limit, a new key is refused with the count your plan allows and the count in use; revoke a key you no longer need first. A rotation also needs room for one more key while the old one winds down.

Creating, rotating and revoking a key need a fresh sign-in. When yours is too old, the dialog asks you to Confirm your identity, sends you through a short sign-in and brings you back with everything you entered.

Creating a key

Create API key opens four steps:

1. Basics — a Name and an optional Description. Name the key after the system that will hold the secret: that is what makes it obvious which key to revoke later.
2. Permissions — the APIs the key may call, in the plan's words: Enriched Data API, Intelligence API, Investigation API (what each opens: plans). Grant the least the application needs. APIs your plan does not include are shown disabled, with the plan that unlocks them. Permissions are fixed once the key exists — changing them means rotating with a new set.
3. Expiry — Never, 30 days, 90 days or 1 year. An expired key stops authenticating but keeps its history. Expiry cannot be extended later.
4. Review — check and create.

The next screen, API key created, shows the secret. Copy it now: it is shown once and cannot be retrieved later — not by you, and not by TraceFast. The secret stays masked until you choose Show secret; Copy secret copies it, and a request sample shows it in use. The screen cannot be dismissed — no Escape, no click outside — until you tick I have stored this secret somewhere safe…; only then does I've saved my key close it. Store it in a secret manager, a CI variable, or an .env file outside the repository.

A timeout or a double click does not create a second key: every retry of one dialog reuses the same request. If the key was created but its secret was lost in transit, the dialog says so — find the key in the list and rotate it to get a secret you can save.

The key list

Keys are listed under Active keys; revoked keys stay below under Revoked, for the record. Each key shows one of five states:

Opening a key shows its Key ID (with Copy key ID — the id, not the secret), the start of the secret as a reminder of which one it is, its Permissions, when it was Last used, and which key it was Replaced by after a rotation. Last used is coarse — it is recorded at most once per interval — and Not reported means usage has not been observed for the key, not that it is unused.

Two facts on the same panel apply to every key:

• Where it works — server-side only. A key does not work from a browser.
• Rate limit — set by the plan. The panel says whether it applies to each key or is shared by every key of the plan.

A permission the plan no longer honours

A key keeps the permissions it was granted, but the API honours only what the plan includes today. When the two differ, the key panel marks the permission Granted, but not honoured and names the plan that includes it — the API refuses those calls with 403 plan_scope_missing. The opposite case — the plan includes an API this key was never granted — is refused with 403 key_scope_missing, and the fix is a key with that permission. See when a key is refused.

MCP for AI agents

Under the key list, MCP for AI agents gives what an AI client needs to reach the same methods over the Model Context Protocol: the server address (with a copy button), how to send a key from this page (X-Api-Key or Authorization: Bearer), and — where your client supports it — signing in to TraceFast instead of using a key. Clients you signed in to are listed under Connected apps. Set up a client → opens MCP server. Calls over MCP count against the key's rate limit and your daily quota, like REST calls.

Rotating a key

Rotate key issues a new secret now and keeps the current key working for a grace period, so you can update every system that holds the old secret. The dialog asks How long should the old key keep working? and offers periods from one hour up to the longest your plan allows; the default is marked. When the period ends the old key stops for good — it cannot be extended afterwards.

The new secret is shown once, exactly as at creation. The new key carries the permissions you choose for it; rotating is also how you change a key's permissions.

To end access without a replacement, revoke the key instead.

Disabling and enabling

Disable switches a key off without destroying it — for an incident, or while you check where it is used. Enable brings it back. A disabled key is refused with 401 key_disabled. A revoked key cannot be enabled.

Revoking a key

Revoke ends a key's access for good. It cannot be undone: the key stays in the list as a record, but it can never authenticate again, and a replacement has to be created. To confirm, you type the key's name. The dialog shows when the key was last used, so you can tell whether anything still calls with it.

Revocation takes effect within the deadline the dialog states before you confirm — 30 seconds of the platform recording it, today. Until then, requests may still succeed; after that, calls are refused with 401 key_revoked.

A subscription change can also revoke keys — see Billing and subscriptions.

Usage

Settings → Usage shows what your keys did, for the last 24 hours, 7 days or 30 days.

Plan quota comes first: today's API requests and page views, each against your plan's daily ceiling, when the count started (00:00 UTC) and when it resets; the monthly ceiling the plan carries; and the request rate by route class — heavier routes draw from their own, smaller allowance as well as the base one. The figures themselves are your plan's — see pricing. Below it:

• Requests — the total, Avg latency and p95 latency;
• Requests per hour, as a chart;
• By key — requests, latency and the last request (UTC) of each key or connected app with traffic;
• How it was called — through an API key or through x402 (pay per call);
• Most-called endpoints — which methods were called;
• Refusals — calls the key check refused, with the reason (By credential), and calls a limit refused (By limit).

Under it, Recent requests lists individual calls — Time (UTC), Key, Endpoint, Called as, Status, Latency and Refusal — for all keys or one. A refusal names the limit that refused in plain words: Heavy routes, for example, means the method's own budget ran out, not Your request rate. See rate limits and quotas.

When the screen cannot load usage, it says so; an error is never shown as "no usage".

Audit log

Settings → Audit log records every operation on your keys — Created, Disabled, Enabled, Rotated, Revoked — including the attempts that were refused, with the reason:

• the plan's key limit was reached;
• a requested permission is not in the plan;
• identity confirmation was needed;
• the key was not in a state that allows it;
• the account is suspended;
• the request was a replay of one already completed;
• the key does not exist.

Each entry shows who acted and from which IP address. Filter by event or by key, and Export CSV to keep a copy.

Keeping keys safe

• Server-side only. Never ship a key in a browser or mobile app — anything that reaches a user's device reaches everyone — and never commit it to a repository.
• One key per system, named after it, with the least permissions it needs. A leak then has one obvious key to rotate.
• On a suspected leak, rotate the key with a short grace period, or revoke it outright; then check Recent requests and the audit log for calls you do not recognise.
• Set an expiry on keys for temporary work.

Related pages

• API keys — sending the key, plans and refusals
• Billing and subscriptions — how a plan change affects keys
• Conventions — requests, responses and errors
• Pricing — plans, quotas and keys per plan

Last updated 22 Oct 2026, 08:06 UTC · verified against TraceFast v1.0.261 · Markdown