---
title: "API access: service tokens"
description: "Plug a dashboard or a script into StatHall with a read-only service token: creation, calls, alerts, rotation and revocation."
lang: en
canonical: "https://www.stathall.com/en/docs/acces-api/"
updated: "2026-10-04"
---

# API access: service tokens


## 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**:

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

```json
{"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.