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

# Authentication

> How to authenticate your requests with the Hoox API

## Overview

The Hoox API uses API keys to authenticate requests. Your API key must be included in the `Authorization` header of all your requests.

## API Key Format

Hoox API keys follow this format:

* **Production**: `hx_live_` followed by 64 hexadecimal characters

Example: `hx_live_1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef`

## Generating an API Key

<Steps>
  <Step title="Access settings">
    Log in to your [Hoox dashboard](https://app.hoox.video) and go to **Your Space** > **Settings** > **API**.
  </Step>

  <Step title="Check your plan">
    Make sure you have at least a **Pro** plan. API access is available from the Pro plan onward.
  </Step>

  <Step title="Generate the key">
    Click **Generate API Key** and give it a descriptive name.
  </Step>

  <Step title="Save the key">
    **Important**: Copy and save your key immediately. It will never be displayed again.
  </Step>
</Steps>

## Using the API Key

### Authentication Header

All requests must include the `Authorization` header:

```http theme={null}
Authorization: Bearer hx_live_your_api_key_here
```

### Implementation Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://app.hoox.video/api/public/v1/voice/list" \
    -H "Authorization: Bearer hx_live_your_api_key_here"
  ```

  ```javascript JavaScript theme={null}
  const headers = {
    'Authorization': 'Bearer hx_live_your_api_key_here',
    'Content-Type': 'application/json'
  };

  const response = await fetch('https://app.hoox.video/api/public/v1/voice/list', {
    headers
  });
  ```

  ```python Python theme={null}
  import requests

  headers = {
      'Authorization': 'Bearer hx_live_your_api_key_here',
      'Content-Type': 'application/json'
  }

  response = requests.get('https://app.hoox.video/api/public/v1/voice/list', headers=headers)
  ```

  ```php PHP theme={null}
  $headers = [
      'Authorization: Bearer hx_live_your_api_key_here',
      'Content-Type: application/json'
  ];

  $ch = curl_init();
  curl_setopt($ch, CURLOPT_URL, 'https://app.hoox.video/api/public/v1/voice/list');
  curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

  $response = curl_exec($ch);
  curl_close($ch);
  ```
</CodeGroup>

## API Key Management

### Revoking a Key

If your key is compromised:

1. Go to **Settings** > **API**
2. Click **Revoke** next to your key
3. Generate a new key immediately
4. Update your applications with the new key

### Regeneration

To renew your key:

1. Click **Regenerate** in the API settings
2. The old key will be immediately revoked
3. Save the new key
4. Update your applications

<Warning>
  Regeneration immediately revokes the old key. Make sure to update all your applications.
</Warning>

## Security

### Best Practices

<AccordionGroup>
  <Accordion title="Secure Storage">
    * Store your keys in environment variables
    * Never commit keys to source code
    * Use secret managers in production
  </Accordion>

  <Accordion title="Key Rotation">
    * Regenerate your keys regularly (every 3-6 months)
    * Monitor your key usage
    * Immediately revoke compromised keys
  </Accordion>

  <Accordion title="Access Restriction">
    * Limit API key access to necessary personnel only
    * Use different keys for different environments
    * Monitor usage logs
  </Accordion>
</AccordionGroup>

### Environment Variables

<CodeGroup>
  ```bash .env theme={null}
  HOOX_API_KEY=hx_live_your_api_key_here
  HOOX_API_URL=https://app.hoox.video/api/public/v1
  ```

  ```javascript Node.js theme={null}
  // Configuration
  const HOOX_API_KEY = process.env.HOOX_API_KEY;
  const HOOX_API_URL = process.env.HOOX_API_URL || 'https://app.hoox.video/api/public/v1';

  if (!HOOX_API_KEY) {
    throw new Error('HOOX_API_KEY environment variable is required');
  }

  // Usage
  const response = await fetch(`${HOOX_API_URL}/voice/list`, {
    headers: {
      'Authorization': `Bearer ${HOOX_API_KEY}`,
      'Content-Type': 'application/json'
    }
  });
  ```

  ```python Python theme={null}
  import os
  import requests

  # Configuration
  HOOX_API_KEY = os.getenv('HOOX_API_KEY')
  HOOX_API_URL = os.getenv('HOOX_API_URL', 'https://app.hoox.video/api/public/v1')

  if not HOOX_API_KEY:
      raise ValueError('HOOX_API_KEY environment variable is required')

  # Usage
  headers = {
      'Authorization': f'Bearer {HOOX_API_KEY}',
      'Content-Type': 'application/json'
  }

  response = requests.get(f'{HOOX_API_URL}/voice/list', headers=headers)
  ```
</CodeGroup>

## Authentication Errors

### Common Error Codes

| Code                  | Status | Description                |
| --------------------- | ------ | -------------------------- |
| `invalid_api_key`     | 401    | Invalid or missing API key |
| `plan_required`       | 403    | Pro plan required          |
| `rate_limit_exceeded` | 429    | Rate limit exceeded        |

### Error Response Example

```json theme={null}
{
  "error": "Invalid API key",
  "details": [
    {
      "code": "invalid_api_key",
      "message": "The provided API key is invalid or has been revoked"
    }
  ]
}
```

## Rate Limiting

Each API key has rate limits:

* **100 requests per minute** for Pro and Enterprise plans
* Limits are applied per workspace
* Response headers indicate your current usage

### Rate Limiting Headers

```http theme={null}
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640995200
```

<Tip>
  Monitor the `X-RateLimit-*` headers to avoid exceeding your limits.
</Tip>