API Authentication

The BlackTide API uses API tokens for authentication. All requests must include a valid Bearer token in the Authorization header.

Creating API Tokens

1. Log in to BlackTide
2. Navigate to Settings → API Tokens
3. Click Create Token
4. Fill in:
   • Name: Descriptive name (e.g., "CI/CD Pipeline")
   • Permissions: Read-only or Read-write
   • Expiration: Never, 30 days, 90 days, 1 year
5. Click Generate Token
6. Copy the token immediately (shown only once)

Using API Tokens

Authorization Header

Include the token in all API requests:

curl https://api.blacktide.xyz/v1/monitors \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

JavaScript/TypeScript

const response = await fetch('https://api.blacktide.xyz/v1/monitors', {
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json'
  }
});

const monitors = await response.json();

Python

import requests

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

response = requests.get(
    'https://api.blacktide.xyz/v1/monitors',
    headers=headers
)

monitors = response.json()

Go

package main

import (
    "net/http"
    "io/ioutil"
)

func main() {
    client := &http.Client{}
    req, _ := http.NewRequest("GET", "https://api.blacktide.xyz/v1/monitors", nil)
    req.Header.Set("Authorization", "Bearer YOUR_API_TOKEN")
    req.Header.Set("Content-Type", "application/json")
    
    resp, _ := client.Do(req)
    body, _ := ioutil.ReadAll(resp.Body)
    // Parse JSON response
}

Token Permissions

Token Security

Best Practices

• Store Securely: Use environment variables, never commit to git
• Rotate Regularly: Regenerate tokens every 90 days
• Use Read-Only: When possible, use read-only tokens
• Set Expiration: Tokens should expire (not "Never")
• Revoke Unused: Delete tokens that are no longer needed

Environment Variables

# .env file (never commit this)
BLACKTIDE_API_TOKEN=btk_abc123xyz789...

# Usage in code
const token = process.env.BLACKTIDE_API_TOKEN;

Error Responses

401 Unauthorized

Token is missing or invalid:

{
  "error": "Unauthorized",
  "message": "Invalid or expired API token",
  "status": 401
}

403 Forbidden

Token lacks required permissions:

{
  "error": "Forbidden",
  "message": "Read-only token cannot create resources",
  "status": 403
}

Rate Limiting

API requests are rate limited to prevent abuse:

Rate Limit Headers

All responses include rate limit information:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 987
X-RateLimit-Reset: 1676304600

429 Too Many Requests

{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Retry after 60 seconds",
  "status": 429,
  "retryAfter": 60
}

API Versioning

The BlackTide API uses URL versioning. Current version: v1

Base URL: https://api.blacktide.xyz/v1/

# All endpoints are versioned
GET /v1/monitors
POST /v1/monitors
GET /v1/incidents

Revoking Tokens

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

Note: Revoked tokens are immediately invalidated. Any requests using that token will return 401 Unauthorized.

Testing Authentication

Test your API token with a simple request:

curl https://api.blacktide.xyz/v1/me \
  -H "Authorization: Bearer YOUR_API_TOKEN"

# Response:
{
  "id": "usr_abc123",
  "email": "user@example.com",
  "name": "John Doe",
  "role": "admin"
}

Next Steps

• Monitors API: Create and manage monitors
• Incidents API: Query incident history
• Alerts API: Configure alert rules and channels
• Status Pages API: Manage status pages programmatically