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

> Authenticate Threetone API requests with a scoped API key in the x-api-key header.

Use an API key for server-to-server requests to the Threetone API.

## Create an API key

Open [API Keys](https://threetone.in/app/developers/api-keys) in the Threetone dashboard and create a key for the integration. Use a separate key for each deployed service and grant only the permissions that service needs.

The secret is shown when the key is created. Store it in a server-side secret manager or environment variable.

```bash theme={null}
export THREETONE_API_KEY="your_api_key"
```

## Send the header

Pass the key in the `x-api-key` request header:

<CodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url https://api.threetone.in/v1/convai/agents \
    --header "x-api-key: $THREETONE_API_KEY"
  ```

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

  response = requests.get(
      "https://api.threetone.in/v1/convai/agents",
      headers={"x-api-key": os.environ["THREETONE_API_KEY"]},
      timeout=30,
  )
  response.raise_for_status()
  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://api.threetone.in/v1/convai/agents", {
    headers: {
      "x-api-key": process.env.THREETONE_API_KEY,
    },
  });

  if (!response.ok) {
    throw new Error(`Threetone API returned ${response.status}`);
  }

  console.log(await response.json());
  ```
</CodeGroup>

Send the key as a header value. Do not put it in a URL, query string, request body, browser bundle, log, or error report.

<Warning>
  Do not send both `x-api-key` and `Authorization` in one request. Threetone rejects requests with ambiguous credentials.
</Warning>

## Handle authentication failures

A `401 Unauthorized` response means the API could not accept the credential. Confirm that the header contains the complete secret and that the key has not expired, been revoked, or been disabled.

A `403 Forbidden` response means the credential was recognized but cannot perform the operation. Check the key's permissions, workspace access, and IP restrictions.

Keep the response's `X-Request-Id` when investigating an error. Never include the API key in a support request.

## Rotate or revoke a key

Create a replacement key, deploy it to every service that needs it, confirm requests succeed, and then revoke the old key. Revoke a key immediately if its value may have been exposed.