Version: 1.4 (Current)

API Keys

Overview

API keys are used to authenticate requests to ToBeAlert's API. Each key has specific permissions and can be configured with an expiration date for enhanced security.

Creating API Keys

Via Web UI

Log in to ToBeAlert
Navigate to Access Control → API Keys
Click Create API key
Fill in the required information:
- Owner: The user who will own the key. Without global admin, this is fixed to your login.
- Expiration date: When the key expires (optional but recommended)
- Permissions: Select the permissions needed. A key cannot receive scopes you do not already hold.
- Description: Optional description of the key's purpose
Click Create

write:keys covers the API Keys menu, list, view (copy / QR), create, edit, duplicate, enable/disable, and delete — only your own keys. There is no read:keys or delete:keys, and no resource-specific admin scope for keys. Seeing all keys and assigning Owner to another user requires global admin (same as Users and Groups), because those actions also need visibility of other users.

Via API

Bash
Python

curl -X POST "http://your-tobealert.com:9000/api/key" \
  -H "Content-Type: application/json" \
  -H "Authorization: Key YOUR_API_KEY" \
  -d '{
         "user": "api-user",
         "scopes": [
             "read:alerts",
             "write:alerts"
         ],
         "text": "Key for monitoring system",
         "expireTime": "2025-12-31T23:59:59Z"
     }'

import requests

response = requests.post(
    "http://your-tobealert.com:9000/api/key",
    headers={
        "Content-Type": "application/json",
        "Authorization": "Key YOUR_API_KEY"
    },
    json={
        "user": "api-user",
        "scopes": [
            "read:alerts",
            "write:alerts"
        ],
        "text": "Key for monitoring system",
        "expireTime": "2025-12-31T23:59:59Z"
    }
)

if response.status_code in [200, 201]:
    print("Request successful")
    print(response.json())
else:
    print(f"Error: {response.status_code}")
    print(response.text)

Required fields:

user: The user who will own the key. Callers without global admin have this forced to their login.
scopes: Array of permission scopes (e.g., ["read:alerts", "write:alerts"]). Cannot include scopes the creator does not hold.
text: Description of the key's purpose

Optional fields:

expireTime: ISO 8601 datetime when key expires

Using API Keys

Include the API key in the Authorization header:

Authorization: Key YOUR_API_KEY_HERE

Example Request

Send a test alert to verify API key works

Bash
Python

curl -X POST "http://your-tobealert.com:9000/api/alert" \
  -H "Content-Type: application/json" \
  -H "Authorization: Key YOUR_API_KEY" \
  -d '{
         "resource": "server-01",
         "event": "service_down",
         "environment": "Production",
         "severity": "critical",
         "text": "Database service is down on server-01"
     }'

import requests

response = requests.post(
    "http://your-tobealert.com:9000/api/alert",
    headers={
        "Content-Type": "application/json",
        "Authorization": "Key YOUR_API_KEY"
    },
    json={
        "resource": "server-01",
        "event": "service_down",
        "environment": "Production",
        "severity": "critical",
        "text": "Database service is down on server-01"
    }
)

if response.status_code in [200, 201]:
    print("Request successful")
    print(response.json())
else:
    print(f"Error: {response.status_code}")
    print(response.text)

API Key Permissions

Permission Categories

Category	Permissions	Description
Alerts	`read:alerts`, `write:alerts`, `delete:alerts`, `admin:alerts`	Alert management
Webhooks	`read:webhooks`, `write:webhooks`	Manage custom webhooks
Services	`read:services`, `write:services`, `admin:services`	Service management
History	`read:history`, `write:history`, `admin:history`	Alert history
Heartbeats	`read:heartbeats`, `write:heartbeats`, `admin:heartbeats`	Heartbeat monitoring
Maintenance	`read:maintenance_windows`, `write:maintenance_windows`, `admin:maintenance_windows`	Maintenance windows
Users	`write:users`, `admin:users`	Manage user accounts
Groups	`read:groups`, `admin:groups`	Manage user groups
Roles	`read:roles`, `admin:roles`	Manage user roles
Keys	`write:keys`	There is no `read:keys` or `delete:keys`, and no resource-specific admin scope for keys. Menu, list, view (copy / QR), create, edit, duplicate, enable/disable, and delete = `write:keys` on the caller's keys only; owner is fixed to their login. Seeing all keys and assigning Owner to another user = global `admin` (same as Users and Groups; you also need to see users). A key cannot receive scopes the creator does not already hold.
Management	`read:management`, `admin:management`	System management
User Info	`read:userinfo`	View user information
Policies	`read:policies`, `write:policies`, `run:policies`, `admin:policies`, `execute:policies`, `execute:policies:<suffix>`, `read:policies_history`, `read:policies_all_history`	Alert policies. List, open, and per-policy history drawer = `read:policies` (does not open `GET /policies/history`). Global history of accessible policies = `read:policies_history`. Global history of all policies = `read:policies_all_history` (implies `read:policies_history`). `admin:policies` and `admin` imply all-history. History delete = `admin:policies`. Manual run = `run:policies` (not implied by `write:policies`) and also requires `write:alerts` (`admin:alerts` or `admin` count). `execute:policies` and `execute:policies:<suffix>` likewise require `write:alerts`. `execute:policies` does not imply `execute:policies:<suffix>` and does not open Permission-gated policies. Those need the exact suffix (or `admin:policies` / `admin`). The policy author, `write:policies`, `run:policies`, and unsuffixed execute are not bypasses. Custom suffixes match policy Permission. Policy Extractions (regex → custom attributes) are part of the policy payload — there are no `*:extractions` scopes.
Incidents	`read:incidents`, `write:incidents`, `write:incident_notes`, `admin:incidents`	Incident management
Workflows	`read:workflow`, `write:workflow`, `admin:workflow`	Workflow management
Service Topologies	`read:service_topologies`, `write:service_topologies`, `admin:service_topologies`	Service topology management and the resource graph
Service History	`read:service_history`, `write:service_history`, `admin:service_history`	Service history management
Alert Sources	`read:alert_sources`, `write:alert_sources`, `admin:alert_sources`	Alert source management
Access Control	`read:accesscontrol`, `write:accesscontrol`	Access control management
Instructions	`write:instructions`, `admin:instructions`, `write:share_instructions`, `admin:share_instructions`	There is no `read:instructions`. Listing and opening pages/media is public for any authenticated caller (no instructions scope). Create, edit, move, upload, and delete = `write:instructions` (no `delete:instructions`). `admin:instructions` includes write. Share links = `write:share_instructions` (independent of write). Administer share links = `admin:share_instructions`. Public `/shared-instruction/…` and public share-check endpoints do not require login.
Notifications	`read:notifications`, `write:notifications`, `admin:notifications`, `write:notification_methods`	Rules, templates, and groups. List / per-rule history drawer / global `GET /notification/rules/history` = `read:notifications` (no separate history scope). Mutate rules/templates/groups = `write:notifications`. Delete history rows = `admin:notifications`. Methods: view with `read:notifications` (secrets masked without write); configure/delete = `write:notification_methods`
Tools	`read:tool`, `write:tool`, `execute:tool`, `admin:tool`, `execute:tool:<suffix>`, `read:tools_history`, `read:tools_all_history`	Custom tools. List, read-only editor, and per-tool history of tools without Permission = `read:tool` (does not open `GET /tools/history`). Global history of accessible tools (Permission + author `createdBy`) = `read:tools_history`. Global history of all tools = `read:tools_all_history` (implies `read:tools_history`). `admin:tool` and `admin` imply all-history. Create, edit, and delete = `write:tool` (no `delete:tool`; write does not imply execute). Manual Try / Run of tools without Permission = `execute:tool` (also requires `write:alerts`; `admin:alerts` or `admin` count). `execute:tool` and `execute:tool:<suffix>` likewise require `write:alerts`. `execute:tool` does not imply `execute:tool:<suffix>` and does not open Permission-gated tools. Those need the exact suffix (or `admin:tool` / `admin`) in addition to read (view), write (mutate), or execute (run). `admin:tool` and `admin` include execute and every suffix. History delete = `admin:tool`. `GET /tools/permissions` lists `execute:tool:<suffix>` values for Roles. Automatic policy/workflow runs do not require the caller’s `execute:tool`. The same rule applies to policies: `execute:policies` does not include `execute:policies:<suffix>`.
Metrics	`read:metrics`, `write:metrics`, `admin:metrics`	Metrics management
KPIs	`read:kpis`, `write:kpis`, `run:kpis`, `admin:kpis`	View list, dashboard (painted uptime), and KPI alerts = `read:kpis`. Create, edit, clone, and delete KPIs and KPI groups = `write:kpis` (does not imply run). On-demand calculate (`POST /service-kpis/<id>/calculate`, `POST /services/<svc>/kpis/calculate`) = `run:kpis`. `admin:kpis` and `admin` include run. No `delete:kpis`.
OEmbed	`read:oembed`	OEmbed support
Dashboards	`read:dashboards_config`, `write:dashboards_config`, `admin:dashboards_config`	Dashboards menu, list all configs, and open non-public dashboards = `read:dashboards_config`. Create, edit, duplicate, and delete = `write:dashboards_config` (no `delete:dashboards_config`). `admin:dashboards_config` includes write and read. Public dashboards: list in the filtered catalog and GET by id without read (`GET` optional). Private id without read → 403.
Playlists	`read:playlists_config`, `write:playlists_config`, `admin:playlists_config`	Playlists button on Dashboards, list playlists, and authenticated play (`/playlists`, `/playlists/:id/play`) = `read:playlists_config`. Create, edit, duplicate, and delete = `write:playlists_config` (no `delete:playlists_config`). `admin:playlists_config` includes write and read. Public player `/playlist/:slug` needs no playlist scope when every dashboard in the playlist is public. Private playlist without read → 403. Do not mix with `dashboards_config`.

Permission Matrix

Action	Required Permission
Send alerts	`write:alerts`
View alerts	`read:alerts`
Create webhooks	`write:webhooks`
View webhooks	`read:webhooks`
View audit log	`read:audit`
Delete alerts	`delete:alerts`
Admin alerts	`admin:alerts`
View user info	`read:userinfo`
API Keys menu, list, view (copy / QR), create, edit, duplicate, enable/disable, or delete own keys	`write:keys`
Same actions on all keys; assign Owner to another user	global `admin` (same as Users and Groups)
Create, edit, or delete services	`write:services`
Admin services	`admin:services`
Admin history	`admin:history`
Admin heartbeats	`admin:heartbeats`
Admin maintenance windows	`admin:maintenance_windows`
Admin users	`admin:users`
Admin groups	`admin:groups`
Admin roles	`admin:roles`
Admin management	`admin:management`
Admin policies	`admin:policies`
Admin workflows	`admin:workflow`
Admin service topologies	`admin:service_topologies`
Admin service history	`admin:service_history`
Admin alert sources	`admin:alert_sources`
Write access control	`write:accesscontrol`
View instructions (list, page, media)	None (public for authenticated callers; no `read:instructions`)
Create, edit, move, upload, or delete instructions	`write:instructions`
Admin instructions (includes write)	`admin:instructions`
Share an instruction with a link	`write:share_instructions`
Administer shared instruction links	`admin:share_instructions`
View notifications (rules/templates/groups/methods) and notification rule history	`read:notifications`
Write notification rules, templates, or groups	`write:notifications`
Delete notification rule execution history	`admin:notifications`
Write notification methods	`write:notification_methods`
`GET /notification/rules/history`, `GET /notification/rules/history/<id>`, `GET /notification/rule/<id>/history`	`read:notifications`
`DELETE /notification/rules/history`	`admin:notifications`
Create, edit, or delete tools	`write:tool`
Run a tool with empty Permission (Try / Run)	`execute:tool` plus `write:alerts` (`admin:alerts` or `admin` count)
View, mutate, or run a tool that sets Permission	Exact `execute:tool:<suffix>` (or `admin:tool` / `admin`) plus `read:tool` / `write:tool` / `execute:tool` for that action; run also needs `write:alerts`
Run a policy manually (preview and apply)	`run:policies` plus `write:alerts` (`admin:alerts` or `admin` count); not implied by `write:policies`
View tools list, editor, and per-tool history (empty Permission)	`read:tool`
`GET /tools/history` and GET history by id (accessible tools only)	`read:tools_history`
`GET /tools/history` for all tools	`read:tools_all_history` (or `admin:tool` / `admin`)
Delete tool execution history	`admin:tool`
`GET /policies/history` and GET history by id (accessible policies only)	`read:policies_history`
`GET /policies/history` for all policies	`read:policies_all_history` (or `admin:policies` / `admin`)
Delete policy execution history	`admin:policies`
Admin tools (includes execute)	`admin:tool`
Write metrics	`write:metrics`
Admin metrics	`admin:metrics`
View KPI list, dashboard (painted uptime), or alerts	`read:kpis`
Create, edit, clone, or delete KPIs and KPI groups	`write:kpis`
Calculate a KPI on demand	`run:kpis`
Admin KPIs (includes run)	`admin:kpis`
View Dashboards menu, list all configs, or open a non-public dashboard	`read:dashboards_config`
List or GET a public dashboard	None (`GET` optional; catalog filtered to public)
GET a private dashboard	`read:dashboards_config` (403 without it)
Create, edit, duplicate, or delete dashboards	`write:dashboards_config`
Admin dashboards (includes write and read)	`admin:dashboards_config`
See Playlists on Dashboards, list playlists, or play authenticated (`/playlists`, `/playlists/:id/play`)	`read:playlists_config`
Play a public playlist at `/playlist/:slug`	None (no playlist scope when all dashboards in it are public)
Play a private playlist without read	Denied (403)
Create, edit, duplicate, or delete playlists	`write:playlists_config`
Admin playlists (includes write and read)	`admin:playlists_config`

Best Practices

Use minimal permissions - Grant only the permissions needed
Set expiration dates - Avoid permanent keys
Rotate keys regularly - Replace keys periodically
Use descriptive names - Identify the purpose of each key
Monitor usage - Track which keys are being used
Secure storage - Keep keys safe, never commit to code repositories

Revoking API Keys

Via Web UI

Navigate to Access Control → API Keys
Find the key you want to revoke
Click Delete
Confirm the deletion

Via API

Delete an API key (requires write:keys; without global admin you can delete only your own)

Bash
Python

curl -X DELETE "http://your-tobealert.com:9000/api/key/YOUR_KEY_ID" \
  -H "Content-Type: application/json" \
  -H "Authorization: Key YOUR_API_KEY"

import requests

response = requests.delete(
    "http://your-tobealert.com:9000/api/key/YOUR_KEY_ID",
    headers={
        "Content-Type": "application/json",
        "Authorization": "Key YOUR_API_KEY"
    }
)

if response.status_code in [200, 201]:
    print("Request successful")
    print(response.json())
else:
    print(f"Error: {response.status_code}")
    print(response.text)

Troubleshooting

Common Issues

401 Unauthorized - Check the key is valid and not expired
403 Forbidden - Verify the key has required permissions or license issues
400 Bad Request - Missing required fields or invalid data

Testing API Keys

warning

This endpoint requires a key with write:keys (own key) or global admin (any key).

Get information about a specific API key

Bash
Python

curl -X GET "http://your-tobealert.com:9000/api/keys/YOUR_KEY_ID" \
  -H "Content-Type: application/json" \
  -H "Authorization: Key YOUR_API_KEY"

import requests

response = requests.get(
    "http://your-tobealert.com:9000/api/keys/YOUR_KEY_ID",
    headers={
        "Content-Type": "application/json",
        "Authorization": "Key YOUR_API_KEY"
    }
)

if response.status_code in [200, 201]:
    print("Request successful")
    print(response.json())
else:
    print(f"Error: {response.status_code}")
    print(response.text)

Overview​

Creating API Keys​

Via Web UI​

Via API​

Using API Keys​

Example Request​

API Key Permissions​

Permission Categories​

Permission Matrix​

Best Practices​

Revoking API Keys​

Via Web UI​

Via API​

Troubleshooting​

Common Issues​

Testing API Keys​

Overview

Creating API Keys

Via Web UI

Via API

Using API Keys

Example Request

API Key Permissions

Permission Categories

Permission Matrix

Best Practices

Revoking API Keys

Via Web UI

Via API

Troubleshooting

Common Issues

Testing API Keys