Secure your agent with authentication and access control

By default, agents created on XUNA AI require authentication to start a conversation. This prevents unauthorized callers from consuming your quota or accessing your agent’s capabilities. Authentication is enforced at the connection layer — clients must present a valid signed URL or conversation token to open a session.

Never expose your XUNA AI API key in client-side code. All authentication artifacts (signed URLs and conversation tokens) must be generated on your server and passed to the client.

Signed URLs

A signed URL is a time-limited URL generated server-side that the client uses to open a WebSocket connection. It embeds your agent ID and authentication credentials so the client never needs your API key. Use signed URLs when you are connecting via the WebSocket API or need fine-grained control over the connection parameters.

Generate a signed URL

from xuna_ai import XunaAI

client = XunaAI()

response = client.conversational_ai.conversations.get_signed_url(
    agent_id="your-agent-id"
)

signed_url = response.signed_url
# Pass this URL to your client

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

const client = new XunaAIClient();

const response = await client.conversationalAi.conversations.getSignedUrl({
  agentId: "your-agent-id",
});

const signedUrl = response.signedUrl;
// Pass this URL to your client

from fastapi import FastAPI
from xuna_ai import XunaAI

app = FastAPI()
client = XunaAI()

@app.get("/get-signed-url")
async def get_signed_url(current_user = Depends(get_current_user)):
    # Authenticate the user before issuing a signed URL
    response = client.conversational_ai.conversations.get_signed_url(
        agent_id="your-agent-id"
    )
    return {"signed_url": response.signed_url}

Use the signed URL on the client

Pass the signed URL to the XUNA AI client SDK instead of the agent ID:

browser.js

import { Conversation } from "@xuna-ai/client";

// Fetch the signed URL from your server
const { signed_url } = await fetch("/get-signed-url").then(r => r.json());

const conversation = await Conversation.startSession({
  signedUrl: signed_url,
});

Conversation tokens

A conversation token is a short-lived token generated server-side that the client uses to initiate a WebRTC session. Conversation tokens also support dynamic variables and session overrides at creation time. Use conversation tokens when you are using the React SDK, mobile SDKs, or any WebRTC-based deployment, or when you want to attach per-session personalization data.

Generate a conversation token

from xuna_ai import XunaAI

client = XunaAI()

token_response = client.conversational_ai.conversations.get_token(
    agent_id="your-agent-id",
    # Optionally attach dynamic variables
    dynamic_variables={
        "user_name": "Jordan",
        "plan_name": "Pro",
    }
)

conversation_token = token_response.token
# Pass this token to your client

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

const client = new XunaAIClient();

const tokenResponse = await client.conversationalAi.conversations.getToken({
  agentId: "your-agent-id",
  // Optionally attach dynamic variables
  dynamicVariables: {
    user_name: "Jordan",
    plan_name: "Pro",
  },
});

const conversationToken = tokenResponse.token;
// Pass this token to your client

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

const app = express();
const client = new XunaAIClient();

app.get("/conversation-token", requireAuth, async (req, res) => {
  const user = req.user;

  const tokenResponse = await client.conversationalAi.conversations.getToken({
    agentId: "your-agent-id",
    dynamicVariables: {
      user_name: user.name,
      account_tier: user.tier,
    },
  });

  res.json({ token: tokenResponse.token });
});

Use the conversation token on the client

Pass the token to the React SDK or client SDK:

import { useConversationControls } from "@xuna-ai/react";

function VoiceAgent() {
  const { startSession } = useConversationControls();

  const handleStart = async () => {
    // Fetch the token from your server
    const { token } = await fetch("/conversation-token").then(r => r.json());

    await startSession({ conversationToken: token });
  };

  return <button onClick={handleStart}>Start</button>;
}

import { Conversation } from "@xuna-ai/client";

const { token } = await fetch("/conversation-token").then(r => r.json());

const conversation = await Conversation.startSession({ token });

Choosing between signed URLs and conversation tokens

	Signed URL	Conversation token
Transport	WebSocket	WebRTC
SDK support	WebSocket API, `@xuna-ai/client`	React SDK, iOS SDK, Android SDK, `@xuna-ai/client`
Session overrides	At connection time	At token creation time
Dynamic variables	At connection time	At token creation time
Typical use	Custom WebSocket clients, low-level integrations	All SDK-based deployments

Public agents

If you want anyone to start a conversation without server-side authentication — for example, a public demo — you can mark the agent as public in the dashboard. Public agents accept connections without a signed URL or token.

Public agents consume your XUNA AI quota for every conversation started. Set a max conversation duration and monitor usage closely to avoid unexpected charges.

Custom authentication middleware

For advanced use cases — such as integrating with your own identity provider or enforcing business-specific access rules — you can implement custom authentication middleware on your server. The pattern is the same for both signed URLs and conversation tokens: your server authenticates the user through whatever mechanism you choose, then issues the XUNA AI credential only if authentication passes. See the server-side examples above for how to integrate user authentication with token generation.

Get Started

Configure

Deploy

Monitor & Optimize

Secure your agent with authentication and access control

Signed URLs

Generate a signed URL

Use the signed URL on the client

Conversation tokens

Generate a conversation token

Use the conversation token on the client

Choosing between signed URLs and conversation tokens

Public agents

Custom authentication middleware

​Signed URLs

​Generate a signed URL

​Use the signed URL on the client

​Conversation tokens

​Generate a conversation token

​Use the conversation token on the client

​Choosing between signed URLs and conversation tokens

​Public agents

​Custom authentication middleware

Signed URLs

Generate a signed URL

Use the signed URL on the client

Conversation tokens

Generate a conversation token

Use the conversation token on the client

Choosing between signed URLs and conversation tokens

Public agents

Custom authentication middleware