ChatBotKit NextAuth SDK

The ChatBotKit SDK for NextAuth.js enables passwordless email authentication that integrates directly with ChatBotKit. This allows you to authenticate users without building separate user management infrastructure.

Two Authentication Approaches

This SDK provides two adapters for different use cases:

1. User Adapter

Use ChatBotKitUserAdapter when each application user needs an isolated ChatBotKit User:

• Separate environments: Each user gets their own bots, datasets, and resources
• Complete isolation: Users cannot see or access each other's data
• User API integration: Requires a parent-user API token
• Best for: SaaS applications, white-label solutions, multi-tenant platforms

2. Contact Adapter (Single Account)

Use ChatBotKitContactAdapter when you want all users to be contacts within a single ChatBotKit account:

• Shared resources: All contacts can interact with the same bots and datasets
• Individual tracking: Each contact has their own conversation history and preferences
• Standard API integration: Works with a regular API token
• Best for: Chat applications, customer support systems, community platforms

Why Use This?

Authentication is complex and risky to build yourself. This SDK lets you skip all of that.

Instead of spending weeks building and maintaining authentication infrastructure, you can:

• Launch faster: Skip building user registration, login, password reset, and account management
• Reduce security risks: No passwords to hash, no credentials to secure, no user data breaches to worry about
• Lower maintenance burden: No authentication-related bugs, no password reset support tickets, no security patches
• Eliminate infrastructure costs: No user database, no email verification system, no password reset flows
• Focus on your product: Spend time building features that make your application unique

Why ChatBotKit?

Build lighter, future-proof AI agents. When you build with ChatBotKit, the heavy lifting happens on our servers-not in your application. This architectural advantage delivers:

• 🪶 Lightweight Agents: Your agents stay lean because complex AI processing, model orchestration, and tool execution happen server-side. Less code in your app means faster load times and simpler maintenance.

• 🛡️ Robust & Streamlined: Server-side processing provides a more reliable experience with built-in error handling, automatic retries, and consistent behavior across all platforms.

• 🔄 Backward & Forward Compatible: As AI technology evolves-new models, new capabilities, new paradigms-your agents automatically benefit. No code changes required on your end.

• 🔮 Future-Proof: Agents you build today will remain capable tomorrow. When we add support for new AI models or capabilities, your existing agents gain those powers without any updates to your codebase.

This means you can focus on building great user experiences while ChatBotKit handles the complexity of the ever-changing AI landscape.

Getting Started

Installation

Add the SDK to your project using npm:

npm install @chatbotkit/nextauth next-auth

User Adapter Configuration

Use this approach when each application user needs an isolated ChatBotKit environment:

import {
  ChatBotKitEmailProvider,
  ChatBotKitUserAdapter,
  MemoryStore,
} from '@chatbotkit/nextauth/user'

const nextAuthConfig = {
  adapter: ChatBotKitUserAdapter({
    token: process.env.CHATBOTKIT_API_TOKEN,

    // Use Redis or another persistent store in production
    store: new MemoryStore(),

    // Control user lifecycle
    autoCreateUser: false,
    autoUpdateUser: true,
    autoDeleteUser: false,
  }),

  providers: [
    ChatBotKitEmailProvider({
      async sendVerificationRequest({ identifier, token }) {
        await sendEmail({
          to: identifier,
          subject: 'Sign in to your account',
          text: `Your verification code is: ${token}`,
        })
      },
    }),
  ],

  session: {
    strategy: 'jwt',
  },

  callbacks: {
    async session({ session, token }) {
      session.user = token.user
      return session
    },
    async jwt({ token, user }) {
      if (user) {
        token.user = user
      }
      return token
    },
  },

  pages: {
    signIn: '/signin',
    signOut: '/signin',
    verifyRequest: '/verify',
  },

  debug: !!process.env.DEBUG,
}

export default nextAuthConfig

Contact Adapter Configuration

Use this approach when users are contacts within a single ChatBotKit account:

import {
  ChatBotKitContactAdapter,
  ChatBotKitContactEmailProvider,
  ContactMemoryStore,
} from '@chatbotkit/nextauth/contact'

const nextAuthConfig = {
  adapter: ChatBotKitContactAdapter({
    token: process.env.CHATBOTKIT_API_TOKEN,

    // Use Redis or another persistent store in production
    store: new ContactMemoryStore(),

    // Control contact lifecycle
    autoCreateContact: true,
    autoUpdateContact: true,
    autoDeleteContact: false,
  }),

  providers: [
    ChatBotKitContactEmailProvider({
      async sendVerificationRequest({ identifier, token }) {
        await sendEmail({
          to: identifier,
          subject: 'Sign in to your account',
          text: `Your verification code is: ${token}`,
        })
      },
    }),
  ],

  session: {
    strategy: 'jwt',
  },

  callbacks: {
    async session({ session, token }) {
      session.user = token.user
      return session
    },
    async jwt({ token, user }) {
      if (user) {
        token.user = user
      }
      return token
    },
  },

  pages: {
    signIn: '/signin',
    signOut: '/signin',
    verifyRequest: '/verify',
  },

  debug: !!process.env.DEBUG,
}

export default nextAuthConfig

Create NextAuth API Route

Create pages/api/auth/[...nextauth].js:

import NextAuth from 'next-auth'

import nextAuthConfig from '../../../nextauth.config.js'

export default NextAuth(nextAuthConfig)

Environment Variables

Add your ChatBotKit API token to .env:

CHATBOTKIT_API_TOKEN=your_api_token_here

Choosing Between User and Contact Adapters

| Feature | User Adapter | Contact Adapter | | ---------------- | ---------------------------------- | --------------------------------------------- | | User isolation | Complete (separate Users) | Partial (shared account, individual contacts) | | Resource sharing | None (each User owns its resources) | Full (all contacts share bots/datasets) | | API type | User API | Standard API | | User identity | Separate ChatBotKit accounts | Contacts within single account | | Best for | SaaS, white-label, multi-tenant | Chat apps, support systems, communities |

Complete Example

A complete working example demonstrating passwordless authentication with the ChatBotKit User API can be found in the user-auth example.

Documentation

For comprehensive information about the ChatBotKit NextAuth SDK, including detailed documentation on its functionalities, helper methods, and configuration options, please visit our type documentation page.

Contributing

If you find a bug or would like to contribute to the ChatBotKit SDK, please open an issue or submit a pull request on the official GitHub repository.