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

# Authentication for the XUNA AI Conversational AI API

> Learn how to authenticate server-side API calls, generate signed URLs for WebSocket connections, and issue conversation tokens for WebRTC clients.

The XUNA AI Conversational AI API uses API keys for server-side requests and short-lived tokens for client-side connections. Choose the right method depending on where your code runs.

## API key

Your API key authenticates every direct HTTP request to the API. Pass it in the `x-api-key` header:

```bash theme={null}
curl https://api.xuna.ai/v1/convai/agents \
  -H "x-api-key: YOUR_API_KEY"
```

Get your key from [**Settings → API Keys**](https://xuna.ai/app/settings/api-keys).

<Warning>
  Never expose your API key in client-side code, browser bundles, or mobile apps. Use signed URLs or conversation tokens for any code that runs outside your server.
</Warning>

Store the key as an environment variable:

```bash theme={null}
export XUNA_AI_API_KEY=your_api_key_here
```

The SDKs read `XUNA_AI_API_KEY` automatically:

<CodeGroup>
  ```python Python theme={null}
  from xuna_ai.client import XunaAI

  # Reads XUNA_AI_API_KEY from the environment
  client = XunaAI()
  ```

  ```typescript TypeScript theme={null}
  import { XunaAIClient } from "@xuna-ai/xuna-ai-js";

  // Reads XUNA_AI_API_KEY from the environment
  const client = new XunaAIClient();
  ```
</CodeGroup>

## Signed URLs (WebSocket)

A signed URL is a pre-authenticated `wss://` address your server generates on demand. Pass it to a browser or mobile client so it can open a WebSocket connection without needing your API key.

### Get a signed URL

`GET /v1/convai/conversation/get-signed-url?agent_id={agent_id}`

<ParamField query="agent_id" type="string" required>
  The ID of the agent you want to start a conversation with.
</ParamField>

<CodeGroup>
  ```python Python theme={null}
  response = client.conversational_ai.conversations.get_signed_url(
      agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6"
  )
  signed_url = response.signed_url
  print(signed_url)  # wss://...
  ```

  ```typescript TypeScript theme={null}
  const response = await client.conversationalAi.conversations.getSignedUrl({
      agentId: "agent_7101k5zvyjhmfg983brhmhkd98n6",
  });
  console.log(response.signedUrl); // wss://...
  ```
</CodeGroup>

**Response:**

<ResponseField name="signed_url" type="string" required>
  A pre-authenticated WebSocket URL (`wss://`). Valid for a short window — generate one per session.
</ResponseField>

<Tip>
  Generate a fresh signed URL for every new conversation. Signed URLs are single-use and expire quickly.
</Tip>

## Conversation tokens (WebRTC)

A conversation token serves the same purpose as a signed URL but for WebRTC-based connections. Your server exchanges your API key for a short-lived token and hands it to the client.

### Get a conversation token

`GET /v1/convai/conversation/token?agent_id={agent_id}`

<ParamField query="agent_id" type="string" required>
  The ID of the agent to start a conversation with.
</ParamField>

<CodeGroup>
  ```python Python theme={null}
  response = client.conversational_ai.conversations.get_token(
      agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6"
  )
  token = response.token
  print(token)
  ```

  ```typescript TypeScript theme={null}
  const response = await client.conversationalAi.conversations.getToken({
      agentId: "agent_7101k5zvyjhmfg983brhmhkd98n6",
  });
  console.log(response.token);
  ```
</CodeGroup>

**Response:**

<ResponseField name="token" type="string" required>
  A short-lived token your client passes when initiating a WebRTC connection.
</ResponseField>

## Choosing an auth method

| Use case                           | Method                        |
| ---------------------------------- | ----------------------------- |
| Server-to-server API calls         | API key in `x-api-key` header |
| Browser WebSocket connection       | Signed URL                    |
| Browser / mobile WebRTC connection | Conversation token            |