Authentication

HostSwarm uses Ed25519 digital signatures for authentication. No passwords, no API keys that can be stolen—just cryptographic proof of identity.

How It Works

  1. Generate keypair: bee1 init creates an Ed25519 private/public key pair
  2. Register: Your public key is registered with HostSwarm
  3. Sign requests: Each API request is signed with your private key
  4. Verify: HostSwarm verifies the signature using your public key

Request Signing

Every authenticated request includes three headers:

HeaderDescription
X-Client-IDYour client identifier (from registration)
X-TimestampUnix timestamp (seconds)
X-SignatureEd25519 signature (hex encoded)

Signature Construction

The signature is computed over a message string:

message = timestamp + method + path + body_hash

Where:
  timestamp  = Unix timestamp as string (e.g., "1703980800")
  method     = HTTP method (e.g., "POST")
  path       = Request path (e.g., "/v1/spine/analyze")
  body_hash  = SHA256 hash of request body (hex), or empty string if no body

Python Example

import hashlib
import time
from nacl.signing import SigningKey

def sign_request(private_key_hex: str, method: str, path: str, body: bytes = None):
    """Sign an API request."""
    timestamp = str(int(time.time()))

    # Compute body hash if body exists
    body_hash = ""
    if body:
        body_hash = hashlib.sha256(body).hexdigest()

    # Build message
    message = f"{timestamp}{method}{path}{body_hash}"

    # Sign with Ed25519
    signing_key = SigningKey(bytes.fromhex(private_key_hex))
    signature = signing_key.sign(message.encode()).signature.hex()

    return {
        "X-Timestamp": timestamp,
        "X-Signature": signature,
    }

cURL Example

# Using openssl for signing (requires private key in PEM format)
timestamp=$(date +%s)
method="GET"
path="/v1/billing/balance"
message="${timestamp}${method}${path}"

# Sign the message
signature=$(echo -n "$message" | \
  openssl pkeyutl -sign -inkey private.pem | \
  xxd -p | tr -d '\n')

# Make request
curl https://api.hostswarm.io/v1/billing/balance \
  -H "X-Client-ID: your-client-id" \
  -H "X-Timestamp: $timestamp" \
  -H "X-Signature: $signature"

Timestamp Validation

Requests are rejected if the timestamp is more than 5 minutes old. This prevents replay attacks.

Clock Sync: Ensure your system clock is synchronized (NTP). Timestamps more than 300 seconds from server time will be rejected.

Key Security

Why Ed25519?