API access: service tokens

Last updated:

What a service token is for

A service token lets a trusted client — a wall dashboard, a monitoring script — read an aggregate of your targets without a browser session. It is read-only: it opens no screen, no other part of the API, and cannot change anything.

Today a token can read one thing: the number of urgent anomalies (P0 and P1) of your targets, and the names of the targets involved. The count follows your Inbox: an anomaly you acknowledge, snooze or resolve leaves the count.

Creating a token

  1. Open Settings › API access. Two-factor authentication must be enabled (Settings › Security).
  2. Click New token and give it a name that says where it lives (“Living-room dashboard”).
  3. Choose its expiration (90 days at most).
  4. If you can, restrict it to your network’s address: Add my current address fills it in, if you create the token from the network where it will be used.
  5. Confirm with your password and a code from your authenticator app.

The token is shown only once. Copy it into the client’s configuration, never into a code repository or a message.

Calling the API

The token goes in the Authorization header, over HTTPS, never in the URL:

curl -H "Authorization: Bearer $STATHALL_TOKEN" \
  https://app.stathall.com/api/v1/service/anomalies/urgentes

{"p0": 2, "p1": 5, "cibles": [{"nom": "ComploDex iOS", "p0": 1, "p1": 2}]}

One read every two minutes is plenty. The list stops at twenty targets, sorted by P0 then P1; the totals cover all your targets.

A refused request always looks the same and does not say why: the detail is in the token’s log (Details button).

What notifies you

You receive a Telegram message (if you have a Telegram channel) and an email:

  • when a token is created or regenerated;
  • on first use from a new address;
  • when a revoked, expired or suspended token is still presented, or from an address outside its list;
  • a week and then a day before it expires.

A token is suspended automatically if it is used abnormally (excessive volume, several new networks in a short time) or if it is seen in a URL or sent without HTTPS. In those last two cases, consider it published: regenerate it.

Regenerating, revoking

Regenerate creates a new token with the same settings; the previous one stays valid for the time you choose (24 hours by default), so you can deploy the new one with no downtime.

Revoke takes effect immediately, on the very next request. Turning off two-factor authentication revokes all your service tokens.