Skip to main content
All requests to the HopX API require authentication using an API key. This guide shows you how to get your API key, configure it securely, and use it in API requests.

​
Get Your API key

Sign up at console.hopx.dev to get your free API key. After creating an account, navigate to the API Keys section in your dashboard to create and manage keys.
Your API key is shown only once when created. Make sure to save it securely. If you lose your key, you’ll need to create a new one from the dashboard.

​
API key Format

HopX API keys follow this format: 
hopx_live_<keyId>.<secret>
Example: 
hopx_live_NXAXAV4sU3Ii.EXi3vR9kOJuhfbR5z42aFx5rhGjH1xnzFdjn9caAqps
The key consists of:
  • Prefix: hopx_live_ (indicates a live/production key)
  • Key ID: 12-character alphanumeric identifier (public, used for identification)
  • Secret: 32-byte cryptographically random secret (base64url encoded)
Never share your API key publicly or commit it to version control. Treat it like a password. If your key is exposed, revoke it immediately and create a new one.

​
Authentication Methods

The HopX API supports two authentication header formats: Include your API key in the Authorization header using Bearer authentication: 
curl -H "Authorization: Bearer $HOPX_API_KEY" \
  https://api.hopx.dev/v1/sandboxes
Replace $HOPX_API_KEY with your actual API key from console.hopx.dev, or set it as an environment variable: export HOPX_API_KEY="your-API key-here"

​
Method 2: X-API key Header

Alternatively, use the X-API key header: 
curl -H "X-API key: $HOPX_API_KEY" \
  https://api.hopx.dev/v1/sandboxes
Replace $HOPX_API_KEY with your actual API key from console.hopx.dev, or set it as an environment variable: export HOPX_API_KEY="your-API key-here"
Both methods are equivalent. Use whichever is more convenient for your setup.

​
Complete Request Example

Here’s a complete authenticated request to create a sandbox: 
curl -X POST https://api.hopx.dev/v1/sandboxes \
  -H "Authorization: Bearer hopx_live_NXAXAV4sU3Ii.EXi3vR9kOJuhfbR5z42aFx5rhGjH1xnzFdjn9caAqps" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "73",
    "timeout_seconds": 3600
  }'

​
Security Best Practices

​
1. Use Environment Variables

Store your API key in an environment variable rather than hardcoding it: 
# Set environment variable
export HOPX_API_KEY="hopx_live_NXAXAV4sU3Ii.EXi3vR9kOJuhfbR5z42aFx5rhGjH1xnzFdjn9caAqps"

# Use in request
curl -H "Authorization: Bearer $HOPX_API_KEY" \
  https://api.hopx.dev/v1/sandboxes

​
2. Use Least Privilege

Only grant API keys the minimum permissions needed for your use case. If you’re only reading sandbox information, don’t use a key with full write access.

​
3. Rotate Keys Regularly

Periodically rotate your API keys, especially if you suspect they may have been compromised. Create new keys in the dashboard and update your applications.

​
4. Monitor Key Usage

Review API key usage in your dashboard to detect any unauthorized access. If you see unexpected activity, revoke the key immediately.

​
Authentication Errors

​
401 Unauthorized

If your API key is missing, invalid, or expired, you’ll receive a 401 error: 
{
  "error": "Unauthorized",
  "code": "AUTHENTICATION_REQUIRED",
  "request_id": "req_abc123"
}
Common causes:
  • Missing Authorization or X-API key header
  • Invalid API key format
  • Revoked or expired API key
Fix:
  • Verify your API key is correct
  • Check that the key hasn’t been revoked in your dashboard
  • Ensure you’re using the correct header format

​
403 Forbidden

If your API key doesn’t have permission for the requested operation: 
{
  "error": "Forbidden",
  "code": "INSUFFICIENT_PERMISSIONS",
  "request_id": "req_abc123"
}
Fix:
  • Verify your API key has the required permissions
  • Check your account’s access level in the dashboard

​
Public Endpoints

The following endpoints do not require authentication:
  • GET /health - Health check endpoint
All other endpoints require a valid API key.

​
Next Steps

  • Quickstart - Create your first sandbox with a complete example
  • Control Plane API - Learn about sandbox management endpoints
  • [Get API key](/API key) - Detailed guide on obtaining and managing API keys