> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hopx.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Learn how to authenticate requests to the HopX API using API keys. Secure your API requests with authentication headers, manage API keys, and understand authentication best practices. Essential for accessing HopX Control Plane and VM Agent APIs. Includes authentication examples, security guidelines, and API key management.

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](https://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.

<Note>
  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.
</Note>

## 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)

<Warning>
  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.
</Warning>

## Authentication Methods

The HopX API supports two authentication header formats:

### Method 1: Authorization Header (Recommended)

Include your API key in the `Authorization` header using Bearer authentication:

```bash theme={null}
curl -H "Authorization: Bearer $HOPX_API_KEY" \
  https://api.hopx.dev/v1/sandboxes
```

<Note>
  Replace `$HOPX_API_KEY` with your actual API key from [console.hopx.dev](https://console.hopx.dev), or set it as an environment variable: `export HOPX_API_KEY="your-API key-here"`
</Note>

### Method 2: X-API key Header

Alternatively, use the `X-API key` header:

```bash theme={null}
curl -H "X-API key: $HOPX_API_KEY" \
  https://api.hopx.dev/v1/sandboxes
```

<Note>
  Replace `$HOPX_API_KEY` with your actual API key from [console.hopx.dev](https://console.hopx.dev), or set it as an environment variable: `export HOPX_API_KEY="your-API key-here"`
</Note>

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:

```bash theme={null}
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:

```bash theme={null}
# 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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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.

## Related

* **\[API key Management]\(/API key)** - Manage API keys in the dashboard
* **[Python SDK Quickstart](/sdk/python/quickstart)** - Get started with the Python SDK
* **[JavaScript SDK Quickstart](/sdk/javascript/quickstart)** - Get started with the JavaScript SDK
* **[API Quickstart](/api/quickstart)** - Make your first API request
* [CLI Reference](/cli/introduction) - Command-line interface

## Next Steps

* **[Quickstart](/api/quickstart)** - Create your first sandbox with a complete example
* **[Control Plane API](/api/control-plane/overview)** - Learn about sandbox management endpoints
* **\[Get API key]\(/API key)** - Detailed guide on obtaining and managing API keys