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

1. Log in to ToBeAlert
2. Navigate to Access Control → API Keys
3. Click Create key
4. Fill in the required information:
   • Owner: The user who will own the key
   • Expiration date: When the key expires (optional but recommended)
   • Permissions: Select the permissions needed
   • Description: Optional description of the key's purpose
5. Click Save

Via API

Bash

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

Python

import requests

response = requests.post(
    "http://your-tobealert.com:9000/api/key",
    headers={
        "Content-Type": "application/json",
        "Authorization": "Key YOUR_ADMIN_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
• scopes: Array of permission scopes (e.g., ["read:alerts", "write:alerts"])
• 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

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"
     }'

Python

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, delete: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	read:keys, write:keys, admin:keys	API key management
Management	read:management, admin:management	System management
User Info	read:userinfo	View user information
Policies	read:policies, write:policies, admin:policies	Alert policies
Workflows	read:workflow, write:workflow, admin:workflow	Workflow management
Service Topologies	read:service_topologies, write:service_topologies, admin:service_topologies	Service topology management
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	System instructions
Notifications - Templates	read:notification-templates, write:notification-templates	Notification template management
Notifications - Groups	read:notification-groups, write:notification-groups	Notification group management
Notifications - Rules	read:notification-rules, write:notification-rules	Notification rule management
Notifications - Methods	read:notification-methods, write:notification-methods	Notification method management
Tools	read:tool, write:tool, admin:tool	Custom tools
Metrics	read:metrics, write:metrics, admin:metrics	Metrics management
KPIs	read:kpis, write:kpis, admin:kpis	KPI management
OEmbed	read:oembed	OEmbed support

Permission Matrix

Action	Required Permission
Send alerts	write:alerts
View alerts	read:alerts
Create webhooks	write:webhooks
View webhooks	read:webhooks
Manage API keys	admin:keys
View audit log	read:audit
Delete alerts	delete:alerts
Admin alerts	admin:alerts
View user info	read:userinfo
Read keys	read:keys
Write keys	write:keys
Admin keys	admin:keys
Delete services	delete: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
Write instructions	write:instructions
Write notification templates	write:notification-templates
Write notification groups	write:notification-groups
Write notification rules	write:notification-rules
Write notification methods	write:notification-methods
Admin tools	admin:tool
Write metrics	write:metrics
Admin metrics	admin:metrics
Write KPIs	write:kpis
Admin KPIs	admin:kpis

Best Practices

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

Revoking API Keys

Via Web UI

1. Navigate to Access Control → API Keys
2. Find the key you want to revoke
3. Click Delete
4. Confirm the deletion

Via API

Delete an API key (requires admin:keys permission)

Bash

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

Python

import requests

response = requests.delete(
    "http://your-tobealert.com:9000/api/key/YOUR_KEY_ID",
    headers={
        "Content-Type": "application/json",
        "Authorization": "Key YOUR_ADMIN_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

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

Testing API Keys

warning

This endpoint requires a key with read:keys permission.

Get information about a specific API key

Bash

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

Python

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)