Docs›Account›API Keys

API Keys

API keys grant programmatic access to your VeloxaHost organization. Each key belongs to the organization and carries only the scopes you give it, so you can follow the principle of least privilege.

Create an API Key

  1. Go to Settings → API Keys → New Key
  2. Give it a name (e.g., github-actions-deploy)
  3. Choose its scopes (see Permission Scopes)
  4. Choose an expiry: 30, 90 or 365 days, or never
  5. Optionally restrict it to an IP allowlist
  6. Click Generate and copy the key immediately — it will not be shown again
⚠️

Store API keys in environment variables or a secret manager (e.g., GitHub Secrets, HashiCorp Vault). Never commit them to version control.

Using the API Key

Pass the key in the Authorization header:

# List instances
curl https://console.veloxahost.com/api/v1/instances \
  -H "Authorization: Bearer veloxa_YOUR_API_KEY"

# Create an instance
curl -X POST https://console.veloxahost.com/api/v1/instances \
  -H "Authorization: Bearer veloxa_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-app",
    "type": "container",
    "image": "ubuntu/24.04",
    "cpu_limit": 1,
    "memory_limit_mb": 1024,
    "disk_size_gb": 20
  }'

Permission Scopes

Scopes are per resource: <resource>:read allows viewing, <resource>:write allows creating, changing and deleting (for example instances:read, dns:write). The scope * grants full access — use it carefully. The full list is in the API reference scope table.

API keys cannot manage team members: inviting, removing and changing the roles of members is done in the console only.

Rotate a Key

To rotate a key without downtime:

  1. Create a new key with the same permissions
  2. Update your application/CI to use the new key
  3. Verify everything works
  4. Delete the old key

Revoke a Key

Delete a key immediately via Settings → API Keys or with the API, using the key's ID (a UUID):

DELETE /api/v1/api-keys/<key-uuid>
Authorization: Bearer veloxa_YOUR_API_KEY

Revoking through the API needs the api-keys:write scope and the owner or admin role.

Revocation takes effect immediately — all requests using that key return 401 Unauthorized.

Related

© 2025 VeloxaHost