←back to manuals

Conversation Sessions

Conversation sessions are a powerful feature that enables client-side applications to securely interact with conversations without requiring your API keys to be exposed to end users. By creating a session token for a specific conversation, you can grant temporary, scoped access that allows client applications to send and receive messages directly, while maintaining security and control.

This approach is essential for building client-side chat interfaces, mobile applications, and interactive web experiences where you need to enable real-time conversation interactions without compromising your account security.

Creating Conversation Sessions

To create a conversation session, you generate a time-limited token that is scoped to a specific conversation. This token can then be used by client-side applications to authenticate requests to conversation endpoints like send, receive, and message creation.

Create a conversation session by sending a POST request to the session creation endpoint:

The API will return a session object containing the conversation ID, a secure token, and an expiration timestamp:

Session Duration

You can specify how long the session token should remain valid by setting the durationInSeconds parameter:

  • Minimum duration: 1,800 seconds (30 minutes)
  • Maximum duration: 86,400 seconds (24 hours)
  • Default duration: 3,600 seconds (1 hour) if not specified

Choose a duration that balances security with user experience. Shorter durations are more secure but may require users to refresh their session more frequently, while longer durations provide a smoother experience but increase the risk if a token is compromised.

Using Session Tokens

Once you have a session token, client-side applications can use it to authenticate requests to conversation endpoints. Include the token in the Authorization header of your requests:

The session token provides access to the following conversation operations:

  • Send messages: Post new messages to the conversation
  • Receive responses: Get AI-generated responses
  • Create messages: Add messages to the conversation history
  • List messages: Retrieve conversation message history

Security Considerations

Conversation sessions are designed with security as a priority:

  • Scoped access: Each token is limited to a single conversation, preventing access to other conversations or account resources
  • Time-limited: Tokens automatically expire after the specified duration, limiting the window of potential misuse
  • No account access: Session tokens cannot be used to access account settings, billing information, or create new resources
  • Revocable: Tokens become invalid once they expire; there is no need for manual revocation

Best Practices:

  • Generate session tokens server-side and pass them to your client application
  • Use HTTPS when transmitting tokens to prevent interception
  • Store tokens securely on the client (e.g., in memory, not localStorage)
  • Implement token refresh logic for long-running applications
  • Monitor token expiration and handle renewal gracefully

Common Use Cases

Conversation sessions are ideal for:

  • Web chat interfaces: Allow users to interact with AI bots directly from your website without exposing API keys
  • Mobile applications: Enable native mobile chat experiences with secure, temporary authentication
  • Third-party integrations: Provide partners with limited access to specific conversations
  • Embedded experiences: Create chat widgets that can be embedded in various platforms securely
  • Multi-user applications: Give each user scoped access to their own conversations

Important Note: Session tokens are meant for end-user interactions. For server-to-server communication or administrative operations, continue using your API keys with full authentication.

conversationsessionauthenticationsecurity