API Tokens

Everything you can do in the dashboard you can do over the REST API: open incidents, switch components, schedule maintenance, push metrics. For that you need a token.

Creating one

Under Account → API Tokens → New token. You set:

• Name — what it is for. "GitHub Actions", "Grafana", "Status monitor". In a year you will want to know which was which.
• Permissions — Read-only or Read and write.
• Expiry — optional. The token works until the end of that day.

The token is shown once. Never again — we store only its hash. Lose it and you create a new one.

Read-only

On the Starter plan the API is always read-only, even with a read & write token; writing starts with Basic.

A read-only token can query everything and change nothing. Every write is refused, whatever your plan allows.

Such a token sees personal data and credentials only masked: email addresses and phone numbers of subscribers and monitor recipients (e.g. j••••@example.com, ••••••••••567) and webhook addresses (the host only). A read and write token sees them in full.

Use it anywhere something only needs to look: a dashboard, a status monitor, a script checking before deployment whether a disruption is running. If such a token goes missing, whoever found it has read your status page — and nothing more.

Bound to the workspace

A token belongs to the workspace you created it in. If you belong to several, it works for that one only. That is deliberate: a token for the customer workspace should not be able to change the internal one by accident.

A useful side effect: you do not need to send a workspace header. The token knows where it belongs.

That is why API Tokens lists only the tokens of the workspace you are in. The exception: tokens from before this binding existed act in all your workspaces and appear in every list, marked "all your workspaces". Replace them with bound ones when you get the chance.

Access to status pages

A token can never do more than the person it belongs to. If your access to single status pages is restricted, the token does not see pages without access (404), and on read only pages every write is refused with 403. GET /api/v1/statuspages lists only the pages you may see.

Using it

curl https://statuswerk.eu/api/v1/statuspage \
  -H "Authorization: Bearer YOUR_TOKEN"

If your workspace has several status pages, pick one with an extra header:

X-Statuspage-Id: <uuid>

Without the header the request goes to the workspace's oldest status page.

The API always answers in English: error messages, status labels, pagination links. What you send yourself (titles, texts) appears as you write it; on the status page and in notifications, the page's language applies.

Revoking

The list shows when each token was last used. Never used after a few weeks is a good sign it can go. Revoke takes effect immediately and cannot be undone.

Tokens created before permissions existed have full access and never expire. They keep working — but if you are touching them anyway, create them afresh.

If your user account is blocked, we delete all your tokens at once; the API and MCP server then answer 401. After an unblock you need new tokens.

Rate limit

The API accepts 120 requests per minute per token. Above that it answers 429 until the minute is up. Calls that test, verify or send a confirmation are limited to 10 per minute. For monitoring asking once a minute that is plenty; for an import in a loop it can be tight — batch the requests in that case.

What exists

The full reference with every endpoint, field and example is at /docs/api, where you can also try calls directly.