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

# Authentication

> Learn how to authenticate with the ThreeTone API

## API Key Authentication

All requests to the ThreeTone API require authentication using an API key. The API key must be included in the request headers.

### Header Format

Include your API key in the `x-api-key` header:

```bash theme={null}
x-api-key: YOUR_API_KEY
```

### Getting Your API Key

<Steps>
  <Step title="Sign Up">
    Sign in to the
    [ThreeTone dashboard](https://threetone.in/app/voice-ai)
  </Step>

  <Step title="Navigate to API Keys">
    Go to **Settings** → **API Keys** in your dashboard
  </Step>

  <Step title="Generate New Key">
    Click **Create New API Key** and give it a descriptive name
  </Step>

  <Step title="Copy and Store">
    Copy your API key immediately - it will only be shown once!
  </Step>
</Steps>

<Warning>
  Store your API keys securely and never commit them to version control.
  Consider using environment variables or a secure key management service.
</Warning>

## Example Request

Here's how to include authentication in your API requests:

<CodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url https://api.threetone.in/v1/convai/agents/list \
    --header 'x-api-key: YOUR_API_KEY' \
    --header 'Content-Type: application/json'
  ```

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

  headers = {
      "x-api-key": "YOUR_API_KEY",
      "Content-Type": "application/json"
  }

  response = requests.get(
      "https://api.threetone.in/v1/convai/agents/list",
      headers=headers
  )
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    "https://api.threetone.in/v1/convai/agents/list",
    {
      method: "GET",
      headers: {
        "x-api-key": "YOUR_API_KEY",
        "Content-Type": "application/json",
      },
    }
  );
  ```
</CodeGroup>

## Authentication Errors

If authentication fails, you'll receive a `401 Unauthorized` response:

```json theme={null}
{
  "detail": "Invalid or missing API key"
}
```

### Common Issues

* **Missing API key**: Ensure the `x-api-key` header is included
* **Invalid API key**: Verify your key is correct and hasn't been revoked
* **Expired API key**: Generate a new key if yours has expired

## Best Practices

<AccordionGroup>
  <Accordion title="Environment Variables">
    Store API keys in environment variables instead of hardcoding them.

    ```bash theme={null}
    export THREETONE_API_KEY="your_api_key_here"
    ```
  </Accordion>

  <Accordion title="Key Rotation">
    Regularly rotate your API keys for enhanced security. You can have multiple
    active keys during transition periods.
  </Accordion>

  <Accordion title="Scope Limitation">
    Use different API keys for different environments (development, staging,
    production) to limit potential exposure.
  </Accordion>
</AccordionGroup>

<Note>
  Need help with authentication? Contact our support team at
  [support@threetone.com](mailto:support@threetone.com)
</Note>