Overview

In a Tambo application, each user has their own threads and messages, isolated from other users' data. This user isolation is achieved through secure token-based authentication.

How Tambo Authentication Works

Tambo uses OAuth 2.0 Token Exchange to securely identify users. Here's what happens:

1. Your app authenticates the user with your chosen OAuth provider (Auth0, Clerk, etc.)
2. Your app receives a JWT token from the provider containing user information
3. Your app exchanges this token with Tambo via the /oauth/token endpoint
4. Tambo returns a Tambo-specific token that identifies the user for all subsequent API calls

sequenceDiagram
    participant User as User
    participant App as Your App
    participant OAuth as OAuth Provider
    participant Tambo as Tambo API

    User->>App: Login request
    App->>OAuth: Authenticate user
    OAuth-->>App: JWT Access Token

    App->>Tambo: POST /oauth/token<br/>(with JWT)
    Tambo-->>App: Tambo Token

    App->>Tambo: API requests<br/>(Authorization: Bearer {tambo-token})
    Tambo-->>App: User's threads & messages

Token Requirements

Tambo supports any OAuth 2.0 provider that issues a JSON Web Token (JWT) with:

• A sub (subject) claim identifying the user
• Proper signature for verification (when JWT verification is enabled)

This includes most popular providers like Google, Microsoft, Auth0, Clerk, and others.

Implementation Approaches

Server-Side Token Retrieval (Recommended)

Best for: Most applications, especially those requiring server-side rendering or enhanced security.

• Tokens are retrieved on the server during page rendering
• More secure as tokens never appear in client-side JavaScript
• Better for SEO and initial page load performance
• Handles authentication state before the client renders

Client-Side Token Retrieval

Best for: Highly interactive applications that need real-time authentication state changes.

• Tokens are retrieved in the browser after the page loads
• Allows for real-time authentication state management
• Required when using client-side routing with authentication guards
• May show loading states during token retrieval

Using TamboProvider

The TamboProvider component from @tambo-ai/react handles the token exchange process automatically:

"use client";
// TamboProvider must be in a client component to manage authentication state

import { TamboProvider } from "@tambo-ai/react";

export default function Layout({ children }: { children: React.ReactNode }) {
  const userToken = useUserToken(); // Get token from your auth provider
  return <TamboProvider userToken={userToken}>{children}</TamboProvider>;
}

Provider-Specific Integration Guides

For detailed integration examples with popular authentication providers, see the following guides:

JWT Verification Strategies

When your OAuth provider supports OpenID Connect Discovery (most do), Tambo automatically verifies tokens. For providers that don't, you can configure verification in your project dashboard:

• OpenID Connect Discovery (Default): Automatic verification using the provider's public keys
• Asymmetric JWT Verification: Manual verification using a provided public key
• Symmetric JWT Verification: Verification using a shared secret (testing only)
• None: No verification (development only)

All verification strategies can be configured in your project dashboard under Settings > User Authentication.