Skip to main content
An API key is a Bearer token for the Tallwatch REST API. Scripts, CI, and MCP clients send it on every request. Browser sessions use a cookie instead, so you do not need a key to use the app UI. Use a key when your code should call the API. Use when an AI agent should call that same API on your behalf. MCP does not replace a key; the server authenticates with one. Pick scopes for the job: read to inspect, write to change monitors or incidents.

​
Create a key

Create a key in . The tw_live_… secret is shown once. Copy it, or Copy prompt to paste MCP setup (a URL plus your key) into Cursor, VS Code, Claude, Codex, Devin, Gemini, Cline, or Continue. If you lose it, revoke and create a new one.
Send the secret as Authorization: Bearer. Keep it out of git and out of query strings. Copy prompt writes the MCP client config for you. Use curl (or any HTTP client) when the caller is your own code.

​
Scopes

A key can have read, write, or both. The key cannot do more than the scopes you gave it. Scopes do not change per request. Give a key only the scopes it needs. A script that lists monitors or incidents needs read. An agent that creates or pauses monitors, or acknowledges or resolves incidents, needs write as well. Missing scope returns 403. The request is authenticated; that action is not allowed for this key. Revoke from the same page. The secret stops working immediately and the key disappears from the list. Create a new key if you still need access. Losing the secret is the same case: you cannot view it again.

​
Pagination and rate limits

List endpoints paginate with limit (1–15, default 15) and next_cursor. Pass the cursor from the previous response until it is absent. are 300 reads / min and 60 writes / min per key (429 with Retry-After and docs_url). Reads are GET and HEAD. Writes are POST, PUT, PATCH, and DELETE. MCP shares these budgets because it uses the same key against the same API. OpenAPI: https://api.tallwatch.com/api/v1/openapi.json. Status-page create/edit and incident comments are app-only today. Agents can write a post-mortem with MCP add_postmortem. For agents, see . For shell and CI, see .