Skip to main content
All API requests require authentication using an API key. You can include your API key in the request headers using one of two methods.

​
Getting an API Key

  1. Sign in to the Hopx Dashboard
  2. Navigate to API Keys section
  3. Create a new API key
  4. Copy and securely store your API key
API keys are sensitive credentials. Never commit them to version control or expose them in client-side code.

​
Authentication Methods

Include your API key in the X-API-Key header: cURL: 
curl -H "X-API-Key: your_api_key_here" \
     https://api.hopx.dev/v1/sandboxes
Python: 
import requests

headers = {
    "X-API-Key": "your_api_key_here",
    "Content-Type": "application/json"
}

response = requests.get(
    "https://api.hopx.dev/v1/sandboxes",
    headers=headers
)
JavaScript: 
const response = await fetch('https://api.hopx.dev/v1/sandboxes', {
  headers: {
    'X-API-Key': 'your_api_key_here',
    'Content-Type': 'application/json'
  }
});

​
Method 2: Authorization Bearer Header

Include your API key in the Authorization header with Bearer prefix: cURL: 
curl -H "Authorization: Bearer your_api_key_here" \
     https://api.hopx.dev/v1/sandboxes
Python: 
import requests

headers = {
    "Authorization": "Bearer your_api_key_here",
    "Content-Type": "application/json"
}

response = requests.get(
    "https://api.hopx.dev/v1/sandboxes",
    headers=headers
)
JavaScript: 
const response = await fetch('https://api.hopx.dev/v1/sandboxes', {
  headers: {
    'Authorization': 'Bearer your_api_key_here',
    'Content-Type': 'application/json'
  }
});

​
Environment Variables

Store your API key in an environment variable for security: cURL: 
export HOPX_API_KEY="your_api_key_here"
curl -H "X-API-Key: $HOPX_API_KEY" \
     https://api.hopx.dev/v1/sandboxes
Python: 
import os
import requests

api_key = os.environ.get("HOPX_API_KEY")

headers = {
    "X-API-Key": api_key,
    "Content-Type": "application/json"
}

response = requests.get(
    "https://api.hopx.dev/v1/sandboxes",
    headers=headers
)
JavaScript: 
const apiKey = process.env.HOPX_API_KEY;

const response = await fetch('https://api.hopx.dev/v1/sandboxes', {
  headers: {
    'X-API-Key': apiKey,
    'Content-Type': 'application/json'
  }
});

​
Authentication Errors

​
401 Unauthorized

If your API key is invalid or missing: 
{
  "error": "Unauthorized",
  "code": "AUTHENTICATION_ERROR"
}
Common Causes:
  • API key is missing from headers
  • API key is incorrect
  • API key has been revoked
  • API key belongs to a different organization

​
403 Forbidden

If your API key is valid but doesn’t have permission: 
{
  "error": "Forbidden",
  "code": "PERMISSION_DENIED"
}
Common Causes:
  • API key doesn’t have required permissions
  • Trying to access resources from another organization

​
Best Practices

​
1. Use Environment Variables

Never hardcode API keys in your code: 
# ❌ Bad
api_key = "hopx_live_abc123..."

# ✅ Good
api_key = os.environ.get("HOPX_API_KEY")

​
2. Rotate Keys Regularly

Regularly rotate your API keys for security:
  1. Create a new API key
  2. Update your applications
  3. Revoke the old key

​
3. Use Different Keys for Different Environments

Use separate API keys for development, staging, and production: 
# Development
export HOPX_API_KEY_DEV="hopx_test_..."

# Production
export HOPX_API_KEY_PROD="hopx_live_..."

​
4. Never Commit Keys to Version Control

Add API keys to .gitignore: 
.env
*.key
secrets/

​
5. Use Key Scoping

When possible, create API keys with limited permissions for specific use cases.

​
Example: Complete Request

cURL: 
curl -X POST https://api.hopx.dev/v1/sandboxes \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "52",
    "timeout_seconds": 3600
  }'
Python: 
import os
import requests

api_key = os.environ.get("HOPX_API_KEY")

headers = {
    "X-API-Key": api_key,
    "Content-Type": "application/json"
}

data = {
    "template_id": "52",
    "timeout_seconds": 3600
}

response = requests.post(
    "https://api.hopx.dev/v1/sandboxes",
    headers=headers,
    json=data
)

print(response.json())
JavaScript: 
const apiKey = process.env.HOPX_API_KEY;

const response = await fetch('https://api.hopx.dev/v1/sandboxes', {
  method: 'POST',
  headers: {
    'X-API-Key': apiKey,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    template_id: '52',
    timeout_seconds: 3600
  })
});

const data = await response.json();
console.log(data);