## 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

1. Log in to your Trulience account
2. Click **Avatar Creator** in the navigation bar
3. Select the avatar you want to secure and click **Edit**
4. Go to the **ADVANCED** tab
5. Find the **Privacy** dropdown and set it to **Private**
6. Save your changes

### 2. Create an API Key

1. Click **Developer** in the navigation bar
2. Go to the **API Keys** tab
3. Click **Create**
4. Give your API key a name
5. Enable the **Generate Tokens** permission
6. 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:**
```json
{
  "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

```json
{
  "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](/docs/developer/api) 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:

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

See the [iFrame documentation](/docs/developer/iframe) for more configuration options.

### JavaScript SDK

Use the `setToken()` method on the Builder:

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

See the [JavaScript SDK documentation](/docs/developer/javascript) for the full API reference.

### React

Pass the token via the `token` prop:

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

See the [React documentation](/docs/developer/react) for more details.

## API Reference

For additional API endpoints including listing avatars, see the [API documentation](/docs/developer/api). To receive notifications when users connect or disconnect from sessions, see the [Webhooks documentation](/docs/developer/webhooks).

## Legacy: Encryption Keys

If you're using the older client-side encryption keys approach, see the [Encryption Keys (Legacy)](/docs/trulience-platform/encryption-keys-legacy) documentation.

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