Skip to main content
Your API key is required to authenticate all requests to the HopX API. This guide shows you how to get your API key, configure it securely, and use it with the SDKs, CLI, or REST API.

​
Get Your API key

Sign up at console.hopx.dev to get your free API key. After creating an account, you’ll find your API key in the dashboard.
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.

​
API key Format

HopX API keys follow this format: 
hopx_live_<keyId>.<secret>
Example: 
hopx_live_NXAXAV4sU3Ii.EXi3vR9kOJuhfbR5z42aFx5rhGjH1xnzFdjn9caAqps
Never share your API key publicly or commit it to version control. Treat it like a password.

​
Setting Your API key

You can provide your API key in several ways. The SDKs check these sources in order: Set the HOPX_API_KEY environment variable. This is the most secure method and keeps your key out of your code.
  • Python
  • JavaScript
# Linux/macOS
export HOPX_API_KEY="hopx_live_..."

# Windows (PowerShell)
$env:HOPX_API_KEY="hopx_live_..."

# Windows (Command Prompt)
set HOPX_API_KEY=hopx_live_...
Then use the SDK without specifying the key:
from hopx_ai import Sandbox

# API key is automatically read from HOPX_API_KEY environment variable
sandbox = Sandbox.create(template="code-interpreter")

​
Method 2: Pass Directly to SDK

You can pass the API key directly when creating a sandbox:
  • Python
  • JavaScript
from hopx_ai import Sandbox

sandbox = Sandbox.create(
    template="code-interpreter",
    api_key="hopx_live_..."  # Pass directly
)
Avoid hardcoding API keys in your source code. Use environment variables or secure secret management systems instead.

​
Method 3: Configuration File

You can use configuration files or secret management systems:
  • Python (.env file)
  • JavaScript (.env file)
  • CLI
# .env file
HOPX_API_KEY=hopx_live_...

# Install python-dotenv: pip install python-dotenv
from dotenv import load_dotenv
load_dotenv()

from hopx_ai import Sandbox

# API key is automatically loaded from .env
sandbox = Sandbox.create(template="code-interpreter")

​
Using API Keys with Direct API Calls

When making direct HTTP requests to the HopX API, include your API key in the request headers:

​
Header Format

You can use either of these header formats: 
# Option 1: Authorization header (recommended)
Authorization: Bearer hopx_live_...

# Option 2: X-API-Key header
X-API-Key: hopx_live_...

​
Example: Creating a Sandbox

curl -X POST https://api.hopx.dev/v1/sandboxes \
  -H "Authorization: Bearer hopx_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "code-interpreter"
  }'

​
Example: Listing Sandboxes

curl https://api.hopx.dev/v1/sandboxes \
  -H "Authorization: Bearer hopx_live_..."

​
Security Best Practices

1

1. Store Keys Securely

Never commit API keys to version control. Use environment variables, secret management services (AWS Secrets Manager, HashiCorp Vault), or secure configuration files.
2

2. Rotate Keys Regularly

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

3. Use Different Keys for Different Environments

Use separate API keys for development, staging, and production environments. This allows you to revoke access to specific environments without affecting others.
4

4. Monitor Key Usage

Regularly review your API key usage in the console to detect any unauthorized access or unusual activity.
5

5. Restrict Key Permissions

If your organization supports it, create API keys with limited permissions for specific use cases (e.g., read-only keys for monitoring).

​
Testing Your API key

You can test your API key by making a simple API call:
  • Python
  • JavaScript
  • cURL
from hopx_ai import Sandbox

try:
    # Try to list templates (requires valid API key)
    templates = Sandbox.list_templates()
    print(f"✅ API key is valid! Found {len(templates)} templates.")
except Exception as e:
    print(f"❌ API key error: {e}")
Expected Output:
✅ API key is valid! Found 15 templates.

​
Troubleshooting

​
Invalid API key Error

If you receive an authentication error:
  1. Verify the key format: Ensure your key starts with hopx_live_ and contains both the key ID and secret separated by a dot.
  2. Check for extra spaces: Make sure there are no leading or trailing spaces when copying the key.
  3. Verify environment variable: If using environment variables, confirm it’s set correctly: 
    echo $HOPX_API_KEY  # Linux/macOS
echo %HOPX_API_KEY%  # Windows
  4. Check key status: Log into console.hopx.dev to verify your key is active and not revoked.

​
Key Not Found

If the SDK can’t find your API key:
  1. Check environment variable name: Ensure it’s exactly HOPX_API_KEY (case-sensitive on some systems).
  2. Restart your terminal/IDE: Environment variables may not be loaded in your current session.
  3. Verify the key is set: Use the troubleshooting commands above to confirm the variable is set.

​
Rate Limiting

If you receive rate limit errors:
  • Your API key has usage limits based on your plan
  • Wait a few moments and retry your request
  • Consider implementing exponential backoff in your application
  • Upgrade your plan if you need higher rate limits

​
Next Steps