Docs
Authentication
Which token to use, where to put it, and what the API answers when access is refused.
Permanent API token
Create a permanent API token in the dashboard. Send it in the JSON body of the request as token:
{
"token": "<your permanent API token>",
"schemaId": "<your scenario id>"
}
Use it for server-to-server calls such as creating sessions, reading statuses and requesting erasure.
User token
A user token is issued when a dashboard user logs in. It goes in the token header of the request, not in the body. Use it for tools that act on behalf of a signed-in dashboard user.
A permanent API token sent in the header is refused.
Token methods
The token methods let you list, create, update and delete tokens. When you create a token you can set an expiry.
IP binding and the IP allowlist
- A token bound to an address and used from another address is refused with
401and the codeIP_MISMATCH. - A request from an address outside your IP allowlist is refused with
403and the messageAccess Denied. - An empty allowlist means requests are accepted from any address.
You manage the allowlist in the dashboard security settings.
Reading errors
The HTTP code is not the only signal. Many failures arrive with a successful HTTP code and an error status in the body, so branch on the status field of the body, and never on the text of a message. A body that is not valid JSON is rejected before any handler runs. See session statuses.
Questions, answered plainly
Where do I keep my permanent API token?
On your server only. Never put it in browser code, a mobile app or a repository.
Can tokens expire?
Yes. When you create a token through the token methods you can give it an expiry.