Overview

The Xelon HQ API provides a comprehensive RESTful interface for managing your cloud infrastructure programmatically. Use the API to automate VM provisioning, manage networks, configure firewalls, and integrate Xelon HQ with your existing toolchain and CI/CD pipelines.

REST API Documentation

For complete endpoint references including request/response schemas, use the interactive API documentation:

Authentication

The Xelon HQ API supports two authentication methods: JWT tokens (for interactive use) and Service Tokens (for automated integrations).

Service Tokens (Recommended for Automation)

Service tokens are long-lived API credentials designed for scripts, CI/CD pipelines, and external integrations. They inherit your user's permissions within a specific organization.

To create a service token, go to My Account > Service Tokens and click Add Service. See Profile & Security > Service Tokens for the full setup guide.

# Using a service token
curl -X GET https://hq.xelon.ch/api/devices \
  -H "Authorization: Bearer YOUR_SERVICE_TOKEN"

# For IP range-based tokens, also include:
  -H "X-User-Id: YOUR_CLIENT_ID"

JWT Tokens (Interactive Use)

For interactive or short-lived use, you can obtain a JWT token by sending your credentials to the login endpoint:

# Authenticate and obtain a JWT token
curl -X POST https://hq.xelon.ch/api/user/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "your-email@example.com",
    "password": "your-password"
  }'

# Response includes a JWT token:
# {
#   "token": "eyJhbGciOiJIUzI1NiIs...",
#   "user": { ... }
# }

# Use the token in subsequent requests:
curl -X GET https://hq.xelon.ch/api/devices \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Token refresh

JWT tokens have a limited lifetime. When a token approaches expiration, use the token refresh endpoint to obtain a new token without re-authenticating with credentials. Include your current valid token in the Authorization header when requesting a refresh.

API Categories

Authentication Example

A complete workflow example: authenticate, list VMs, and get details for a specific VM.

# Step 1: Authenticate
TOKEN=$(curl -s -X POST https://hq.xelon.ch/api/user/login \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "password"}' \
  | jq -r '.token')

# Step 2: List all virtual machines
curl -s -X GET https://hq.xelon.ch/api/devices \
  -H "Authorization: Bearer $TOKEN" \
  | jq '.data'

# Step 3: Get details for a specific VM
curl -s -X GET https://hq.xelon.ch/api/devices/{device-id} \
  -H "Authorization: Bearer $TOKEN" \
  | jq '.'

Rate Limiting

The API enforces rate limits to ensure fair usage and platform stability. When rate limits are exceeded, the API returns a 429 Too Many Requests response. Certain write operations (such as creating devices) have stricter rate limits than read operations.

API Versioning

The Xelon HQ API supports two versions: