Skip to main content
Hopx uses API keys to authenticate requests. Get your API key from the dashboard and configure it using environment variables or pass it directly to the SDK.

​
Quick Start

Get authenticated in 3 steps:
1

Get Your API Key

Create an account and generate an API key in the dashboard.

Get API Key

Sign up and create your first API key
2

Set Environment Variable

Set the HOPX_API_KEY environment variable:
  • Linux/macOS
  • Windows (PowerShell)
export HOPX_API_KEY=hopx_live_YOUR_KEY_HERE
3

Use the SDK

The SDK automatically reads the API key from the environment variable:
  • Python
  • JavaScript/TypeScript
from hopx_ai import Sandbox

# API key automatically read from HOPX_API_KEY
sandbox = Sandbox.create(template="code-interpreter")
You’re authenticated! The SDK will automatically use your API key for all requests.

​
Getting Your API Key

1

Sign Up

Create an account at console.hopx.dev
2

Navigate to API Keys

Go to Settings → API Keys in the dashboard
3

Create New Key

Click “Create API Key” and give it a descriptive name (e.g., “Development”, “Production”)
4

Copy Key Immediately

Copy the full API key immediately - you won’t be able to see it again after closing the dialog!
Keep your API keys secure! Never commit them to version control, share them publicly, or log them in plain text.

​
API Key Format

Hopx API keys follow this format: 
hopx_live_<keyId>.<secret>
Example: 
hopx_live_NXAXAV4sU3Ii.EXi3vR9kOJuhfbR5z42aFx5rhGjH1xnzFdjn9caAqps
Components:
  • Prefix: hopx_live_ (constant)
  • Key ID: 12 characters (base62 alphanumeric)
  • Secret: ~43 characters (base64url encoded, 32 bytes)
The secret part is only shown once when you create the key. Store it securely - it cannot be recovered if lost.

​
Authentication Methods

The SDK automatically reads the HOPX_API_KEY environment variable. This is the recommended approach for all environments. Set the environment variable:
  • Linux/macOS
  • Windows (PowerShell)
  • Windows (CMD)
# Temporary (current session)
export HOPX_API_KEY=hopx_live_YOUR_KEY_HERE

# Permanent (add to ~/.bashrc or ~/.zshrc)
echo 'export HOPX_API_KEY=hopx_live_YOUR_KEY_HERE' >> ~/.bashrc
source ~/.bashrc
Use in code:
  • Python
  • JavaScript/TypeScript
from hopx_ai import Sandbox

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

​
Method 2: Pass Directly (Quick Testing)

For quick testing or scripts, you can pass the API key directly:
  • Python
  • JavaScript/TypeScript
from hopx_ai import Sandbox

sandbox = Sandbox.create(
    template="code-interpreter",
    api_key="hopx_live_YOUR_KEY_HERE"
)
Not recommended for production! Use environment variables or secrets managers instead.

​
Method 3: .env File (Development)

For local development, use a .env file: Create .env file: 
# .env
HOPX_API_KEY=hopx_live_YOUR_KEY_HERE
Add .env to your .gitignore to prevent committing secrets!
Load in your code:
  • Python
  • JavaScript/TypeScript
pip install python-dotenv

from dotenv import load_dotenv
from hopx_ai import Sandbox

# Load .env file
load_dotenv()

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

​
Advanced Topics

For production environments, use a secrets manager:
  • AWS Secrets Manager
  • Google Secret Manager
  • HashiCorp Vault
import boto3
import json
from hopx_ai import Sandbox

# Get secret from AWS
client = boto3.client('secretsmanager', region_name='us-west-2')
response = client.get_secret_value(SecretId='hopx-ai/api-key')
secret = json.loads(response['SecretString'])

# Use API key
sandbox = Sandbox.create(
    template="code-interpreter",
    api_key=secret['HOPX_API_KEY']
)
Use different keys for different environments:
  • Python
  • JavaScript/TypeScript
import os
from hopx_ai import Sandbox

# Determine environment
env = os.getenv('ENVIRONMENT', 'development')

# Use appropriate key
api_keys = {
    'development': os.getenv('HOPX_API_KEY_DEV'),
    'staging': os.getenv('HOPX_API_KEY_STAGING'),
    'production': os.getenv('HOPX_API_KEY_PROD'),
}

sandbox = Sandbox.create(
    template="code-interpreter",
    api_key=api_keys[env]
)
API keys can have different scopes for fine-grained access control:
ScopePermissionsUse Case
Full AccessCreate, read, update, delete sandboxesProduction applications
Read-OnlyList and view sandboxesMonitoring, dashboards
Create-OnlyCreate new sandboxes onlyIsolated services
Configure scopes in the dashboard.
Rotate your API keys regularly for security:
1

Create New Key

Generate a new API key in the dashboard
2

Update Applications

Deploy new key to all applications (use blue-green deployment for zero downtime)
3

Verify

Monitor logs to ensure new key works correctly
4

Revoke Old Key

Delete old key from dashboard after 24-48 hours

​
Error Handling

Handle authentication errors gracefully:
  • Python
  • JavaScript/TypeScript
from hopx_ai import Sandbox, AuthenticationError

try:
    sandbox = Sandbox.create(
        template="code-interpreter",
        api_key="invalid-key"
    )
except AuthenticationError as e:
    print(f"Authentication failed: {e.message}")
    print(f"Status code: {e.status_code}")  # 401
    print(f"Request ID: {e.request_id}")
Common authentication errors:
Error CodeMessageSolution
auth_invalid_keyInvalid API keyCheck key format and validity
auth_key_expiredAPI key expiredRotate to new key
auth_insufficient_permissionsInsufficient permissionsUse key with correct scope
auth_rate_limitedRate limit exceededWait or upgrade plan

​
Security Best Practices

Store API keys in environment variables or secrets managers, never in code.
# ✅ Good
api_key = os.getenv('HOPX_API_KEY')

# ❌ Bad
api_key = "hopx_live_YOUR_KEY_HERE"
Rotate API keys every 90 days or when team members leave.
Separate keys for development, staging, and production.
Set up alerts for unusual activity in the dashboard.
Add .env and secrets files to .gitignore.
# .gitignore
.env
.env.local
secrets/
*.key
Use secure methods to share keys (password manager, secrets manager).
Redact keys in logs and error messages.
# ✅ Good
logging.info(f"Using API key: {api_key[:15]}...")

# ❌ Bad
logging.info(f"Using API key: {api_key}")

​
Testing Authentication

Verify your API key is working:
  • Python
  • JavaScript/TypeScript
from hopx_ai import Sandbox, AuthenticationError

def test_authentication():
    try:
        # Try to create a sandbox
        sandbox = Sandbox.create(template="code-interpreter")
        print(f"✅ Authentication successful!")
        print(f"   Sandbox ID: {sandbox.sandbox_id}")
        sandbox.kill()
        return True
    except AuthenticationError as e:
        print(f"❌ Authentication failed: {e.message}")
        return False

if __name__ == "__main__":
    test_authentication()

​
Next Steps

Quickstart

Create your first sandbox

Core Concepts

Learn about sandboxes and templates

Security Guide

Security best practices

Rate Limits

Understand API rate limits
Need help? Contact support@hopx.dev or join Discord.