Skip to main content
An API key lets a script, a CI job, the MCP server, or a Terraform run talk to Tallwatch without a browser session. You create a key in the dashboard, copy it once, and send it as a Bearer token on every request. Tallwatch stores only a SHA-256 hash of the key, so a key cannot be recovered after you close the dialog.

​
Create a key

1

Open API keys

Go to Settings → API keys and click Create API key. Give it a name you’ll recognise later (for example ci-deploy or terraform).
2

Pick scopes and expiry

Choose read, write, or both, and an expiry (never, 30 days, 90 days, or a year). Scopes default to read if you pick nothing.
3

Copy the key now

The full key, which starts with tw_live_, is shown once. Copy it and store it in a secret manager or an environment variable. Once you dismiss the dialog, Tallwatch has only the hash and cannot show it again.
The key is shown a single time. If you lose it, revoke it and create a new one. There is no way to retrieve a key after the create dialog closes.
In the list, each key shows its visible prefix (for example tw_live_a4f2), its scopes, when it was last used, and its expiry. That prefix is enough to identify a key in your logs without exposing the secret.

​
Authenticate

Send the key as a Bearer token in the Authorization header:
A request with no key and no session cookie returns 401 with { "code": "no_session" }.

​
Scopes

Scopes are deliberately coarse in v1: a key carries read, write, or both. If a key lacks the scope a route needs, the request returns 403 with { "code": "insufficient_scope", "required_scope": "write" }. Give a key only the scopes it needs: a read-only dashboard exporter should never hold a write key.

​
What a key can reach

These routes accept a Bearer key. Anything not listed (bulk pause/resume/delete, the “test now” check, status-page create/edit, incident comments, rename, and post-mortems) stays session-only in v1.

​
Pagination

The list endpoints (/monitors, /incidents, /status-pages) are cursor-paginated, and the pagination is opt-in so older integrations keep working.
  • With no pagination params, a list returns the legacy shape: { "items": [...] }, the whole set.
  • With a cursor or limit param, it returns { "data": [...], "next_cursor": "..." }. The items field is mirrored alongside data on this path too, so a legacy reader still works.
Pass limit to size a page (default 50, max 100) and follow next_cursor to walk the rest. When next_cursor is null, you’ve reached the last page.
The cursor is an opaque token. Don’t parse it or build one yourself; just hand back the value Tallwatch gave you.

​
Rate limit

Bearer requests are rate limited per key: 120 requests per minute by default. Session (cookie) requests from the dashboard are not affected. Every response carries the standard rate-limit headers so you can pace yourself before you hit the wall: When you go over, the request returns 429 with { "code": "rate_limited", "retry_after_sec": <seconds> } and a Retry-After header set to the same number of seconds. Wait that long, then retry.

​
Revoke a key

Delete a key from Settings → API keys to revoke it. Revocation is a soft delete: the key stops working immediately, but the row stays in the list (greyed out) so the audit trail survives. Revoking is the right move the moment a key leaks or a script is retired.

​
OpenAPI spec

The public API ships an OpenAPI 3.1 spec at a public URL, with no auth required:
It describes the monitor, incident, and status-page routes, the Bearer security scheme, and the paginated response shapes. Point Postman, Insomnia, or a client generator at it to scaffold a typed client.
Tallwatch is pre-1.0. Scopes are coarse (read / write) by design in this release; per-resource scopes are a later concern. The rate limit is enforced per API replica, so a key’s effective ceiling scales with the number of API instances.