Authentication for the XUNA AI Conversational AI API

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:

curl https://api.xuna.ai/v1/convai/agents \
  -H "x-api-key: YOUR_API_KEY"

Get your key from Settings → API Keys.

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.

Store the key as an environment variable:

export XUNA_AI_API_KEY=your_api_key_here

The SDKs read XUNA_AI_API_KEY automatically:

from xuna_ai.client import XunaAI

# Reads XUNA_AI_API_KEY from the environment
client = XunaAI()

import { XunaAIClient } from "@xuna-ai/xuna-ai-js";

// Reads XUNA_AI_API_KEY from the environment
const client = new XunaAIClient();

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}

string

required

The ID of the agent you want to start a conversation with.

response = client.conversational_ai.conversations.get_signed_url(
    agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6"
)
signed_url = response.signed_url
print(signed_url)  # wss://...

const response = await client.conversationalAi.conversations.getSignedUrl({
    agentId: "agent_7101k5zvyjhmfg983brhmhkd98n6",
});
console.log(response.signedUrl); // wss://...

Response:

string

required

A pre-authenticated WebSocket URL (wss://). Valid for a short window — generate one per session.

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

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}

string

required

The ID of the agent to start a conversation with.

response = client.conversational_ai.conversations.get_token(
    agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6"
)
token = response.token
print(token)

const response = await client.conversationalAi.conversations.getToken({
    agentId: "agent_7101k5zvyjhmfg983brhmhkd98n6",
});
console.log(response.token);

Response:

string

required

A short-lived token your client passes when initiating a WebRTC connection.

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

Overview

Agents

Telephony

Authentication for the XUNA AI Conversational AI API

API key

Signed URLs (WebSocket)

Get a signed URL

Conversation tokens (WebRTC)

Get a conversation token

Choosing an auth method

​API key

​Signed URLs (WebSocket)

​Get a signed URL

​Conversation tokens (WebRTC)

​Get a conversation token

​Choosing an auth method

API key

Signed URLs (WebSocket)

Get a signed URL

Conversation tokens (WebRTC)

Get a conversation token

Choosing an auth method