Client-Side Access Tokens

Client-side access tokens enable direct client integration without requiring a server proxy. Your end users can authenticate securely and interact with their agents directly from your frontend application.

With client-side access tokens, you can provide secure user authentication where users authenticate directly with their own tokens. This enables direct client integration without the need for server-side proxy endpoints, while maintaining granular permissions per user and enhanced security through auto-expiring tokens.

Creating client-side access tokens

1
from letta_client import Letta
2
3
# Initialize the client
4
client = Letta(token="YOUR_TOKEN", project="YOUR_PROJECT")
5
6
# Create the token
7
client.client_side_access_tokens.create(
8
    policy=[
9
        {
10
            "type": "agent",
11
            "id": "id",
12
            "access": ["read_messages"],
13
        }
14
    ],
15
    hostname="hostname",
16
)

Token policy configuration

When creating client-side access tokens, you configure granular permissions through the policy parameter.

Policy structure

Each policy entry consists of a type (currently supports “agent”), an id for the specific resource, and an access array containing the permissions for that resource.

Available permissions

For agent resources, you can grant read_messages permission to read agent messages, write_messages permission to send messages to the agent, read_agent permission to read agent metadata and configuration, and write_agent permission to update agent metadata and configuration.

Token expiration

You can specify a custom expiration time using the expires_at parameter:

1
client = Letta(token="YOUR_TOKEN", project="YOUR_PROJECT")
2
client_token = client.client_side_access_tokens.create(
3
    policy=[/* ... */],
4
    hostname="https://your-app.com",
5
    expires_at="2024-12-31T23:59:59Z",  # Optional, ISO 8601 format
6
)

Security considerations

When implementing client-side access tokens, it’s important to follow security best practices. Tokens are automatically bound to the specified hostname to prevent unauthorized use, but this security feature can be easily bypassed, it merely exists to prevent accidental usage in wrong hostnames. Hackers can always spoof request headers. You should grant only the minimum permissions required for your use case, following the principle of least privilege. Additionally, regularly create new tokens and delete old ones to maintain security, and store tokens securely in your client application using appropriate browser APIs.

Deleting tokens

You can delete client-side access tokens when they’re no longer needed:

1
client = Letta(token="YOUR_TOKEN", project="YOUR_PROJECT")
2
client.client_side_access_tokens.delete("ck-let-token-value")

Example use case: multi-user chat application

Here’s how you might implement client-side access tokens in a multi-user chat application:

1
# Server-side: Create user-specific tokens when users log in
2
def create_user_token(user_id: str, agent_id: str):
3
    client_token = client.client_side_access_tokens.create(
4
        policy=[
5
            {
6
                "type": "agent",
7
                "id": agent_id,
8
                "access": ["read_messages", "write_messages"],
9
            }
10
        ],
11
        hostname="https://chat.yourapp.com",
12
        expires_at=(datetime.now() + timedelta(hours=24)).isoformat(),  # 24 hours
13
    )
14
    return client_token.token
15
16
# Client-side: Use the token to communicate directly with the agent
17
user_client = Letta(token=user_token, project="YOUR_PROJECT")  # Received from your backend
18
19
# Send messages directly to the agent
20
response = user_client.agents.messages.create(
21
    agent_id=agent_id,
22
    messages=[
23
        {
24
            "role": "user",
25
            "content": "Hello, agent!",
26
        }
27
    ],
28
)

This approach eliminates the need for server-side API proxying while maintaining secure, isolated access for each user.