# User Authentication
URL: /concepts/user-authentication

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](https://datatracker.ietf.org/doc/html/rfc8693) 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

<Mermaid
  chart="
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)](https://datatracker.ietf.org/doc/html/rfc7519) 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:

```tsx title="Basic Setup"
"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>;
}
```

<Callout type="info" title="Why Client Component Required">
  TamboProvider needs to be in a client component because it manages
  authentication state, handles token refresh, and provides React context to
  child components. Server components cannot manage state or provide React
  context.
</Callout>

## Provider-Specific Integration Guides

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

<Cards>
  <Card href="/guides/add-authentication/nextauth" title="Auth.js">
    Learn how to integrate Tambo with Auth.js using Google OAuth as an example.
  </Card>

  <Card href="/guides/add-authentication/auth0" title="Auth0">
    Step-by-step guide for integrating Tambo with Auth0 authentication.
  </Card>

  <Card href="/guides/add-authentication/clerk" title="Clerk">
    Complete example of using Tambo with Clerk's authentication system.
  </Card>

  <Card href="/guides/add-authentication/supabase" title="Supabase">
    Integration guide for Supabase Auth with Tambo in Next.js applications.
  </Card>

  <Card href="/guides/add-authentication/neon" title="Neon">
    How to use Tambo with Auth.js and Neon PostgreSQL database integration.
  </Card>

  <Card href="/guides/add-authentication/workos" title="WorkOS">
    Enterprise-grade authentication with WorkOS and Tambo integration.
  </Card>

  <Card href="/guides/add-authentication/better-auth" title="Better Auth">
    Modern authentication toolkit with built-in support for multiple providers
    and plugins.
  </Card>
</Cards>

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

<Callout type="warn" title="Supabase Exception">
  Supabase Auth doesn't support asymmetric JWT verification. You'll need to
  disable JWT verification in your Tambo project settings when using Supabase.
</Callout>

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