Customisation

Security

Securing your avatars with private access and API key authentication

For LLMs

Overview

Private avatars require a JWT token for authentication, which you generate server-side using an API key.

Setting Up Private Avatars

1. Make Your Avatar Private

Log in to your Trulience account
Click Avatar Creator in the navigation bar
Select the avatar you want to secure and click Edit
Go to the ADVANCED tab
Find the Privacy dropdown and set it to Private
Save your changes

2. Create an API Key

Click Developer in the navigation bar
Go to the API Keys tab
Click Create
Give your API key a name
Enable the Generate Tokens permission
Click Create to generate your API key

Copy and store your API key securely. You’ll need it to generate JWT tokens from your backend.

API keys use the format tru_live_ followed by a unique identifier.

Generate Token Endpoint

Use this endpoint from your backend to generate JWT tokens for avatar authentication.

Request

POST /auth/generate-token

Headers:

x-api-key: tru_live_***
Content-Type: application/json

Body:

{
  "avatar_id": "4386676996480451678",
  "expire_at": 300
}

Field	Type	Required	Description
`avatar_id`	string	Yes	The ID of the avatar to generate a token for
`expire_at`	integer	No	Token expiry in seconds. Default: 120. Range: 60-3600

Success Response

{
  "jwt": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 300,
  "avatar_id": "4386676996480451678"
}

Field	Type	Description
`jwt`	string	JWT token for avatar authentication
`expires_in`	integer	Token expiry in seconds (matches requested `expire_at` or default 120)
`avatar_id`	string	Avatar ID the token is valid for

Notes

Tokens are single-use and cannot be refreshed
Generate a new token for each user session
See the API documentation for error responses

Using the Token

Once you’ve generated a token on your backend, pass it to the Trulience client. The method depends on how you’re integrating:

iFrame

Append the token as a query parameter:

<iframe src="https://www.trulience.com/avatar/<your-avatar-id>?token=<your-jwt-token>"></iframe>

See the iFrame documentation for more configuration options.

JavaScript SDK

Use the setToken() method on the Builder:

let trulience = Trulience.Builder()
    .setAvatarId("your_avatar_id")
    .setToken("your_jwt_token")
    .build();

See the JavaScript SDK documentation for the full API reference.

React

Pass the token via the token prop:

<TrulienceAvatar
    avatarId={config.avatarId}
    token={config.avatarToken}
/>

See the React documentation for more details.

API Reference

For additional API endpoints including listing avatars, see the API documentation. To receive notifications when users connect or disconnect from sessions, see the Webhooks documentation.

Legacy: Encryption Keys

If you’re using the older client-side encryption keys approach, see the Encryption Keys (Legacy) documentation.

The API key approach documented above is recommended for new integrations as it keeps your signing credentials server-side.