Usage in Production

When deploying to production, do not expose your API key publicly. Instead:

Exchange your API key for a short-lived session token on the server side.
Pass this token to the client.
Initialize the TruGen SDK with the session token.

Getting a Session Token

Session tokens are valid for 5 minutes by default. You should request a new token for each user session rather than caching tokens long-term.

The session token endpoint must be called from your server, not from client-side code. Making this request from the browser would expose your API key.

Fetching a Session Token on Your Server

From your server, make a request to get a session token by referencing your Agent ID (create and get one here):

interface SessionTokenResponse {
  token: string;
}

interface SessionTokenOptions {
  userName?: string;
  userId?: string;
}

async function getSessionToken(
  apiKey: string,
  agentId: string,
  options?: SessionTokenOptions
): Promise<string> {
  const response = await fetch("https://api.trugen.ai/v1/auth/conversation", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-API-Key": apiKey,
    },
    body: JSON.stringify({
      agentId,
      userName: options?.userName,
      userId: options?.userId,
    }),
  });

  if (!response.ok) {
    const error = await response.text();
    throw new Error(`Failed to get session token: ${response.status} ${error}`);
  }

  const data: SessionTokenResponse = await response.json();
  return data.token;
}

async function getSessionToken(apiKey, agentId, options) {
  const response = await fetch("https://api.trugen.ai/v1/auth/conversation", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-API-Key": apiKey,
    },
    body: JSON.stringify({
      agentId,
      userName: options?.userName,
      userId: options?.userId,
    }),
  });

  if (!response.ok) {
    const error = await response.text();
    throw new Error(`Failed to get session token: ${response.status} ${error}`);
  }

  const data = await response.json();
  return data.token;
}

User Identity Configuration

When generating a session token, you can optionally provide details about the user connecting to the conversation session:

userName: A string representing the user’s name (defaults to "JS SDK" if omitted).
userId: A unique string identifying the user. If omitted, the SDK automatically generates a timestamp-based ID (e.g. usr_2026_06_25t12_49_49_168175).

These values are passed inside the JSON request body when calling https://api.trugen.ai/v1/auth/conversation.

Example Request Body

{
  "agentId": "your-agent-id-here",
  "userName": "Alice Smith",
  "userId": "user_alice_123"
}

Common Error Responses

Status Code	Meaning	Solution
400	Invalid request body or malformed `agentId`	Check your request body format or verify your Agent ID is a valid UUID
401	Invalid, missing, or expired API Key	Verify your API key is correct and included in the `X-API-Key` header
500	Agent not found or database error	Verify that the Agent ID exists and belongs to your account

JavaScript SDK

Python SDK

Getting a Session Token

Fetching a Session Token on Your Server

User Identity Configuration

Example Request Body

Common Error Responses

​Getting a Session Token

​Fetching a Session Token on Your Server

​User Identity Configuration

​Example Request Body

​Common Error Responses

Getting a Session Token

Fetching a Session Token on Your Server

User Identity Configuration

Example Request Body

Common Error Responses