API Authentication

All StatusRadar API requests require authentication using Bearer tokens. This guide covers token types, how to obtain them, and how to use them in requests.

Authentication Methods

StatusRadar uses Bearer Token Authentication for all API requests.

Bearer Token Format

Include your token in the Authorization header:

Authorization: Bearer YOUR_API_TOKEN

Example request:

curl -H "Authorization: Bearer abc123def456..." \
  https://api.statusradar.dev/v1/monitors

Token Types

StatusRadar uses three types of tokens for different purposes:

1. User API Tokens

Purpose: General API access for managing monitors, incidents, and status pages

Permissions: Full account access (same as logged-in user)

Use cases:

• Integrations with third-party tools
• Custom dashboards
• Automation scripts
• CI/CD pipelines

Example:

eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...

2. Agent Tokens

Purpose: Server monitoring agents

Permissions: Limited to submitting server metrics and retrieving agent configuration

Use cases:

• StatusRadar agent installation
• Server health reporting
• Plugin metrics submission

Example:

bbc279c3ec3f8f68d9734b560222512d30a373fd6e5a6039a6a02d7eb143b232

3. Probe Tokens

Purpose: Distributed monitoring probe servers

Permissions: Limited to retrieving checks and submitting results

Use cases:

• Probe server authentication
• Distributed check execution
• Check result submission

Example:

d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0e1f2g3h4i5j6

Obtaining API Tokens

User API Tokens

Via Dashboard:

1. Log in to https://statusradar.dev
2. Go to Dashboard → Settings → API Tokens
3. Click Generate New Token
4. Give your token a descriptive name (e.g., "Production Integration")
5. Copy the token (shown only once!)
6. Store token securely

Important: Token is shown only once during creation. If lost, generate a new token.

Agent Tokens

Via Dashboard:

1. Go to Dashboard → Servers → Add Server
2. Token is automatically generated
3. Copy the installation command or token
4. Use in agent installation:

TOKEN='your-agent-token' \
bash -c "$(curl -sL https://statusradar.dev/install-agent.sh)"

Or manually configure:

# /opt/statusradar/config/agent.yaml
api:
  token: your-agent-token

Probe Tokens

Probe tokens are provided by StatusRadar team for authorized probe servers. Contact [email protected] to set up a probe server.

Using Tokens

HTTP Header

Include token in Authorization header with Bearer prefix:

GET /v1/monitors HTTP/1.1
Host: api.statusradar.dev
Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json

curl Examples

List monitors:

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
  https://api.statusradar.dev/v1/monitors

Create monitor:

curl -X POST \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"My Website","url":"https://example.com","type":"http"}' \
  https://api.statusradar.dev/v1/monitors

Get monitor details:

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
  https://api.statusradar.dev/v1/monitors/123

Delete monitor:

curl -X DELETE \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  https://api.statusradar.dev/v1/monitors/123

Python Examples

Using requests library:

import requests

API_TOKEN = 'YOUR_API_TOKEN'
BASE_URL = 'https://api.statusradar.dev/v1'

headers = {
    'Authorization': f'Bearer {API_TOKEN}',
    'Content-Type': 'application/json'
}

# List monitors
response = requests.get(f'{BASE_URL}/monitors', headers=headers)
monitors = response.json()

# Create monitor
data = {
    'name': 'My Website',
    'url': 'https://example.com',
    'type': 'http'
}
response = requests.post(f'{BASE_URL}/monitors', json=data, headers=headers)
monitor = response.json()

# Update monitor
data = {
    'name': 'Updated Name',
    'enabled': True
}
response = requests.put(f'{BASE_URL}/monitors/123', json=data, headers=headers)

# Delete monitor
response = requests.delete(f'{BASE_URL}/monitors/123', headers=headers)

JavaScript Examples

Using fetch API:

const API_TOKEN = 'YOUR_API_TOKEN';
const BASE_URL = 'https://api.statusradar.dev/v1';

const headers = {
  'Authorization': `Bearer ${API_TOKEN}`,
  'Content-Type': 'application/json'
};

// List monitors
const response = await fetch(`${BASE_URL}/monitors`, { headers });
const monitors = await response.json();

// Create monitor
const data = {
  name: 'My Website',
  url: 'https://example.com',
  type: 'http'
};
const response = await fetch(`${BASE_URL}/monitors`, {
  method: 'POST',
  headers,
  body: JSON.stringify(data)
});
const monitor = await response.json();

// Update monitor
const updateData = {
  name: 'Updated Name',
  enabled: true
};
const response = await fetch(`${BASE_URL}/monitors/123`, {
  method: 'PUT',
  headers,
  body: JSON.stringify(updateData)
});

// Delete monitor
await fetch(`${BASE_URL}/monitors/123`, {
  method: 'DELETE',
  headers
});

PHP Examples

Using cURL:

<?php
$token = 'YOUR_API_TOKEN';
$baseUrl = 'https://api.statusradar.dev/v1';

$headers = [
    'Authorization: Bearer ' . $token,
    'Content-Type: application/json'
];

// List monitors
$ch = curl_init($baseUrl . '/monitors');
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
$monitors = json_decode($response, true);
curl_close($ch);

// Create monitor
$data = [
    'name' => 'My Website',
    'url' => 'https://example.com',
    'type' => 'http'
];

$ch = curl_init($baseUrl . '/monitors');
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
$monitor = json_decode($response, true);
curl_close($ch);

Token Security

Best Practices

1. Never commit tokens to version control:

# ✅ Good - use environment variables
export STATUSRADAR_TOKEN="your-token"

# ❌ Bad - hardcoded in code
api_token = "abc123def456..."

2. Use environment variables:

import os

API_TOKEN = os.environ.get('STATUSRADAR_TOKEN')
if not API_TOKEN:
    raise ValueError('STATUSRADAR_TOKEN environment variable not set')

3. Store tokens securely:

• Use secret management tools (AWS Secrets Manager, HashiCorp Vault)
• Use .env files (add to .gitignore)
• Use CI/CD secret variables
• Never log tokens
• Never expose in client-side code

4. Rotate tokens regularly:

• Generate new tokens periodically
• Revoke old tokens
• Update all systems using the token

5. Use separate tokens for different environments:

# Development
STATUSRADAR_TOKEN_DEV="dev-token-here"

# Staging
STATUSRADAR_TOKEN_STAGING="staging-token-here"

# Production
STATUSRADAR_TOKEN_PROD="prod-token-here"

.env File Example

# .env
STATUSRADAR_API_URL=https://api.statusradar.dev/v1
STATUSRADAR_TOKEN=your-api-token-here

Load in Python:

from dotenv import load_dotenv
import os

load_dotenv()

API_URL = os.getenv('STATUSRADAR_API_URL')
API_TOKEN = os.getenv('STATUSRADAR_TOKEN')

Load in Node.js:

require('dotenv').config();

const API_URL = process.env.STATUSRADAR_API_URL;
const API_TOKEN = process.env.STATUSRADAR_TOKEN;

Token Management

Listing Tokens

View all your API tokens in Dashboard:

1. Go to Dashboard → Settings → API Tokens
2. See list of all tokens with:
   • Token name
   • Creation date
   • Last used date
   • Actions (revoke)

Revoking Tokens

Via Dashboard:

1. Go to Dashboard → Settings → API Tokens
2. Find token to revoke
3. Click Revoke
4. Confirm action

Revoked tokens:

• Immediately stop working
• Return HTTP 401 Unauthorized
• Cannot be restored (must generate new token)

Token Expiration

User API Tokens:

• Do not expire automatically
• Remain valid until revoked
• Recommended: Rotate every 90 days

Agent Tokens:

• Do not expire
• Valid for lifetime of server
• Revoke when decommissioning server

Probe Tokens:

• Managed by StatusRadar team
• Contact support for rotation

Authentication Errors

401 Unauthorized

Error:

{
  "error": true,
  "message": "Unauthorized",
  "code": "unauthorized",
  "status": 401
}

Causes:

1. Missing Authorization header
2. Invalid token
3. Revoked token
4. Malformed token

Solutions:

# Check token is included
curl -v -H "Authorization: Bearer YOUR_TOKEN" ...

# Verify token format (no extra spaces)
# Correct:
Authorization: Bearer abc123

# Wrong:
Authorization: Bearer  abc123  # Extra spaces
Authorization: Bearer: abc123   # Extra colon

403 Forbidden

Error:

{
  "error": true,
  "message": "Forbidden",
  "code": "forbidden",
  "status": 403
}

Causes:

1. Token lacks required permissions
2. Agent token used for user API endpoints
3. Accessing resources owned by different account

Solutions:

• Use correct token type for endpoint
• Verify token has required permissions
• Check resource ownership

Testing Authentication

Test Token Validity

curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://api.statusradar.dev/v1/monitors

# Expected: HTTP 200 + monitors list
# If invalid: HTTP 401 Unauthorized

Test Different Endpoints

# User API endpoint
curl -H "Authorization: Bearer USER_TOKEN" \
  https://api.statusradar.dev/v1/monitors

# Agent API endpoint
curl -H "Authorization: Bearer AGENT_TOKEN" \
  https://api.statusradar.dev/v1/agent/config

# Probe API endpoint
curl -H "Authorization: Bearer PROBE_TOKEN" \
  https://api.statusradar.dev/v1/probe/get-checks

Rate Limiting

Authenticated requests have higher rate limits:

• With token: 1000 requests/hour
• Without token: 100 requests/hour

See API Overview for details.

Common Mistakes

1. Missing Bearer Prefix

# ❌ Wrong
Authorization: abc123def456

# ✅ Correct
Authorization: Bearer abc123def456

2. Extra Spaces

# ❌ Wrong (space after Bearer)
Authorization: Bearer  abc123

# ✅ Correct
Authorization: Bearer abc123

3. Wrong Token Type

# ❌ Wrong - using agent token for user API
curl -H "Authorization: Bearer AGENT_TOKEN" \
  https://api.statusradar.dev/v1/monitors

# ✅ Correct - use user API token
curl -H "Authorization: Bearer USER_API_TOKEN" \
  https://api.statusradar.dev/v1/monitors

4. Token in URL (Insecure)

# ❌ Wrong - token in URL (logs, browser history)
https://api.statusradar.dev/v1/monitors?token=abc123

# ✅ Correct - token in header
curl -H "Authorization: Bearer abc123" \
  https://api.statusradar.dev/v1/monitors

5. Hardcoded Tokens

# ❌ Wrong - hardcoded
api_token = "abc123def456"

# ✅ Correct - environment variable
api_token = os.environ.get('STATUSRADAR_TOKEN')

Integration Examples

Postman

1. Create new request
2. Set request URL: https://api.statusradar.dev/v1/monitors
3. Go to Authorization tab
4. Type: Bearer Token
5. Token: Paste your API token
6. Send request

Insomnia

1. Create new request
2. Set request URL
3. Click Auth dropdown
4. Select Bearer Token
5. Paste token in Token field
6. Send request

CI/CD (GitHub Actions)

name: Monitor Check
on: [push]

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - name: Check monitors
        env:
          STATUSRADAR_TOKEN: ${{ secrets.STATUSRADAR_TOKEN }}
        run: |
          curl -H "Authorization: Bearer $STATUSRADAR_TOKEN" \
            https://api.statusradar.dev/v1/monitors

CI/CD (GitLab CI)

check_monitors:
  script:
    - >
      curl -H "Authorization: Bearer $STATUSRADAR_TOKEN"
      https://api.statusradar.dev/v1/monitors
  variables:
    STATUSRADAR_TOKEN: $CI_STATUSRADAR_TOKEN

Troubleshooting

Authentication Not Working

Check 1: Verify token format

# Print token (first 20 chars)
echo "${STATUSRADAR_TOKEN:0:20}"

# Check for hidden characters
echo "$STATUSRADAR_TOKEN" | od -c

Check 2: Test with curl verbose

curl -v -H "Authorization: Bearer $STATUSRADAR_TOKEN" \
  https://api.statusradar.dev/v1/monitors

Check 3: Verify header is sent

# Should see: Authorization: Bearer abc123...
curl -v -H "Authorization: Bearer $TOKEN" ... 2>&1 | grep Authorization

Token Recently Revoked

If you revoked a token, it stops working immediately. Generate a new token and update all systems.

Expired Token

User API tokens don't expire automatically. If getting 401 errors:

1. Verify token wasn't revoked
2. Check token is correct (no typos)
3. Generate new token if needed

Security Considerations

Token Leakage

If token is compromised:

1. Immediately revoke token in dashboard
2. Generate new token
3. Update all systems
4. Review access logs
5. Check for unauthorized activity

Audit Logs

Monitor token usage:

1. Go to Dashboard → Settings → API Tokens
2. Check "Last Used" timestamp
3. Review for unexpected usage

IP Restrictions (Coming Soon)

Future feature: Restrict token usage to specific IP addresses or CIDR ranges.

Next Steps

• API Overview - Learn about API structure and conventions
• Monitors API - Start managing monitors via API
• Agent API - Integrate server monitoring
• Probe API - Set up distributed monitoring