API Authentication

Bloqd supports multiple authentication methods depending on your use case.

Authentication Methods

Method	Use Case	Format
API Key	Agents, scripts, integrations	Authorization: Bearer f2b_xxx
JWT	Dashboard, user sessions	Authorization: Bearer eyJhbG...

API Key Authentication

API keys are the primary method for programmatic access and agent communication.

API Key Format

API keys follow this format:

f2b_[32 random characters]

Example:

f2b_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

Using API Keys

Include the API key in the Authorization header:

curl -X GET "https://bloqd.example.com/api/v1/servers" \
  -H "Authorization: Bearer f2b_your_api_key_here"

Permission Levels

API keys have one of three permission levels:

Level	Permissions
read	View servers, bans, whitelist, templates
write	All read + report bans, modify whitelist, execute commands
admin	All write + create API keys, manage settings, delete servers

Creating API Keys

Via Dashboard:

1. Go to Settings → API Keys
2. Click Create Key
3. Enter a name and select permission level
4. Click Create

Save Your Key

The full API key is only shown once. Save it securely.

Via API:

curl -X POST "https://bloqd.example.com/api/v1/keys" \
  -H "Authorization: Bearer f2b_admin_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CI/CD Integration",
    "permissions": "write"
  }'

Response:

{
  "id": 5,
  "name": "CI/CD Integration",
  "key": "f2b_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  "permissions": "write",
  "created_at": "2024-01-15T10:30:00Z"
}

Server-Bound Keys

API keys can optionally be bound to a specific server:

curl -X POST "https://bloqd.example.com/api/v1/keys" \
  -H "Authorization: Bearer f2b_admin_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "web-01 agent",
    "permissions": "write",
    "server_id": 1
  }'

Server-bound keys can only access data for that specific server.

Revoking API Keys

Via Dashboard:

1. Go to Settings → API Keys
2. Find the key to revoke
3. Click Delete

Via API:

curl -X DELETE "https://bloqd.example.com/api/v1/keys/5" \
  -H "Authorization: Bearer f2b_admin_key"

JWT Authentication

JWT (JSON Web Tokens) are used for user sessions in the dashboard.

Login

curl -X POST "https://bloqd.example.com/api/v1/auth/login" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "admin",
    "password": "your_password"
  }'

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
  "user": {
    "id": 1,
    "username": "admin",
    "role": "admin"
  }
}

Using JWT

Include the access token in requests:

curl -X GET "https://bloqd.example.com/api/v1/users/me" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Token Refresh

Access tokens expire after a short period. Use the refresh token to get a new one:

curl -X POST "https://bloqd.example.com/api/v1/auth/refresh" \
  -H "Content-Type: application/json" \
  -d '{
    "refresh_token": "eyJhbGciOiJIUzI1NiIs..."
  }'

Logout

curl -X POST "https://bloqd.example.com/api/v1/auth/logout" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

MFA (Multi-Factor Authentication)

If MFA is enabled, login returns a challenge:

{
  "mfa_required": true,
  "mfa_token": "mfa_challenge_token"
}

Complete MFA verification:

curl -X POST "https://bloqd.example.com/api/v1/auth/mfa/verify" \
  -H "Content-Type: application/json" \
  -d '{
    "mfa_token": "mfa_challenge_token",
    "code": "123456"
  }'

Rate Limiting

API requests are rate limited to prevent abuse:

Endpoint Type	Limit
Standard	100 requests/minute
Sensitive (login, keys)	10 requests/minute

Rate limit headers are included in responses:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1705320600

When rate limited, you'll receive a 429 Too Many Requests response.

Security Best Practices

API Keys

1. Use least privilege - Create keys with minimum required permissions
2. Rotate regularly - Delete and recreate keys periodically
3. Don't commit keys - Never store API keys in version control
4. Use environment variables - Store keys in env vars, not code
5. Monitor usage - Check last_used timestamps for anomalies

User Sessions

1. Enable MFA - Require TOTP for all admin users
2. Use strong passwords - Minimum 12 characters
3. Regular logout - Don't leave sessions open

Network

1. Use HTTPS - Never send credentials over HTTP
2. Firewall - Restrict API access to known IPs
3. VPN - Consider VPN for admin access

Error Responses

401 Unauthorized

Missing or invalid authentication:

{
  "error": "Unauthorized",
  "message": "Invalid or missing API key"
}

403 Forbidden

Valid authentication but insufficient permissions:

{
  "error": "Forbidden",
  "message": "Admin permission required"
}

429 Too Many Requests

Rate limit exceeded:

{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Try again in 60 seconds."
}

Code Examples

Python

import requests

API_KEY = "f2b_your_api_key"
BASE_URL = "https://bloqd.example.com/api/v1"

headers = {
    "Authorization": f"Bearer {API_KEY}"
}

# Get all servers
response = requests.get(f"{BASE_URL}/servers", headers=headers)
servers = response.json()

JavaScript/Node.js

const API_KEY = 'f2b_your_api_key';
const BASE_URL = 'https://bloqd.example.com/api/v1';

async function getServers() {
  const response = await fetch(`${BASE_URL}/servers`, {
    headers: {
      'Authorization': `Bearer ${API_KEY}`
    }
  });
  return response.json();
}

cURL

#!/bin/bash
API_KEY="f2b_your_api_key"
BASE_URL="https://bloqd.example.com/api/v1"

# Get all servers
curl -s -X GET "${BASE_URL}/servers" \
  -H "Authorization: Bearer ${API_KEY}" | jq .

Next Steps

• API Endpoints - Explore available endpoints
• WebSocket API - Real-time updates
• Error Codes - All error responses