How API tokens work

An API token is a secret that lets software call the OnlineOrNot API for one organisation. You choose its permissions and expiration when you create it.

Use API tokens for scripts, integrations, and other software that cannot sign in through the dashboard.

How a token is used

An API token follows four stages:

1. Create - choose a name, expiration, and permissions.
2. Copy - save the secret when OnlineOrNot displays it.
3. Use - send it to api.onlineornot.com in the Authorization header.
4. Replace or delete - create a replacement before it expires, or delete it to stop it from working.

The raw secret is returned when the token is created. It is not included when tokens are listed or viewed later. If the secret is lost, delete the token and create a replacement.

Using a token

Send the secret in the Authorization header:

Authorization: Bearer your-api-token

OnlineOrNot checks the token, its expiration, and its permissions on every request.

API tokens are not JWTs. Do not try to decode them or read permissions from the token itself.

Organisation scope

Each token belongs to one organisation. It cannot access a different organisation.

Give each token a name that says who uses it and what it is for. For example, use production-deploy, terraform, or incident-bot instead of token-1.

Grants and permissions

A grant gives the token READ or EDIT permission for one part of OnlineOrNot.

Scope	Covers
Uptime Checks	Uptime, browser, DNS, and TCP checks
Heartbeat Checks	Heartbeat monitors
Maintenance	Maintenance windows
Status Pages	Status pages, components, incidents, and subscribers
People	Organisation members and invitations
Integrations	Notification integrations
API Tokens	API token management
Webhooks	Generic webhook endpoints

READ lets the token view data. EDIT lets it view and change data.

An API token cannot create another API token, even with API Tokens: EDIT. Create replacements through the dashboard or an authorized OAuth client.

An invalid, deleted, or expired token returns 401 Unauthorized. A valid token without the required permission returns 403 Forbidden.

Only give a token the permissions it needs. A reporting tool usually needs READ, while a tool that creates or changes monitors needs EDIT.

Expiration and deletion

Tokens can expire after a set period, on a custom date, or never. Expired tokens remain listed in the dashboard but no longer work.

Deleting a token removes it permanently and stops it from working on later requests.

Tokens cannot be edited in place. To change grants or expiration:

1. Create a replacement token through the dashboard or an authorized OAuth client.
2. Update the application that uses it.
3. Confirm the replacement works.
4. Delete the old token.

Do not delete the old token until you have confirmed that the replacement works.

API tokens, sessions, and OAuth

OnlineOrNot uses different sign-in methods for different jobs:

Credential	Intended use
API token	Scripts and other software
Dashboard session	A person using the web dashboard
OAuth access token	Connected apps and the OnlineOrNot CLI

The OnlineOrNot CLI uses OAuth. You do not need to create and copy an API token to sign in to the CLI.

Security model

Anyone who gets an API token can use its permissions until it expires or is deleted.

• Store tokens in a secrets manager or protected environment variable.
• Never commit tokens to source control.
• Avoid putting tokens in URLs, logs, screenshots, or error messages.
• Use the shortest practical expiration.
• Create separate tokens for separate systems.
• Delete credentials that are no longer used.

For endpoint details and request examples, see the API Tokens reference.