Authentication

SwarmStack uses Bearer token authentication to secure all API endpoints. This guide covers how to obtain, use, and manage your API tokens.

Bearer Tokens

All authenticated API requests must include a valid Bearer token in the Authorization header.

Authorization: Bearer sk-swarm-your-api-key-here

Token Format

SwarmStack API keys follow the format:

sk-swarm-{environment}-{random-hex-string}

Where:

• sk-swarm - Standard prefix for all SwarmStack keys
• {environment} - Either prod or dev
• {random-hex-string} - 64-character unique identifier

Making Authenticated Requests

Using cURL

curl -H "Authorization: Bearer sk-swarm-prod-xxxxx" \
     "https://api.swarmstack.net/api/ls?path=/opt/swarm"

Using JavaScript (fetch)

const response = await fetch('https://api.swarmstack.net/api/ls?path=/opt/swarm', {
  headers: {
    'Authorization': 'Bearer sk-swarm-prod-xxxxx'
  }
});
const data = await response.json();

Using Python (requests)

import requests

headers = {
    'Authorization': 'Bearer sk-swarm-prod-xxxxx'
}

response = requests.get(
    'https://api.swarmstack.net/api/ls',
    params={'path': '/opt/swarm'},
    headers=headers
)
data = response.json()

Authentication Errors

When authentication fails, the API returns one of these responses:

Error Response Format

{
  "error": "Unauthorized",
  "message": "Invalid or missing authentication token"
}

Security Best Practices

Environment Variables

Store your API key in environment variables:

# Add to your shell profile (.bashrc, .zshrc, etc.)
export SWARM_API_KEY="sk-swarm-prod-xxxxx"

# Use in scripts
curl -H "Authorization: Bearer $SWARM_API_KEY" \
     "https://api.swarmstack.net/api/health"

Key Rotation

For security, you should rotate your API keys periodically:

1. Generate a new API key from your dashboard
2. Update all applications using the old key
3. Revoke the old key once migration is complete
4. Never keep both keys active longer than necessary

IP Allowlisting

For production deployments, consider restricting API access to specific IP addresses. Contact support to enable IP allowlisting for your account.

Public Endpoints

Some endpoints don't require authentication: