Contact-Based NextAuth Adapter for Single-Account Multi-User Authentication

We're excited to announce a powerful new authentication option for the ChatBotKit Node.js SDK: the ChatBotKit Contact Adapter for NextAuth.js. This new adapter enables developers to build multi-user applications where authenticated users are managed as contacts within a single ChatBotKit account, opening up streamlined workflows for customer portals, chat applications, and support systems.

A New Approach to Multi-User Authentication

While our existing Partner Adapter creates separate sub-accounts for each user—ideal for SaaS and white-label solutions—the new Contact Adapter takes a different approach. It manages all authenticated users as contacts within your main ChatBotKit account, allowing them to share resources like bots and datasets while maintaining individual conversation histories and preferences.

This architecture is perfect for scenarios where you want multiple users interacting with the same AI assistants. Think customer support portals where users chat with your support bot, community platforms with shared AI resources, or any application where user isolation isn't required but individual tracking is essential.

Passwordless Authentication Made Simple

The Contact Adapter integrates seamlessly with NextAuth.js, providing a complete passwordless authentication solution using secure 6-character verification codes. Unlike traditional magic link flows, users simply enter a short code from their email—making authentication more accessible and user-friendly, especially on mobile devices or cross-device scenarios.

The accompanying ChatBotKitContactEmailProvider generates cryptographically secure tokens with configurable expiration times, giving you full control over the authentication experience while maintaining security best practices.

Flexible User Lifecycle Management

Developers gain fine-grained control over how contacts are created and managed through three key configuration options:

• Auto-create contacts: Enable automatic contact creation on first sign-in for self-service applications, or disable it to manually approve new users.
• Auto-update contacts: Keep contact information synchronized on each sign-in, ensuring your data stays current across authentication sessions.
• Auto-delete contacts: Choose whether contacts should be removed when users are deleted from NextAuth, giving you control over data retention policies.

This flexibility means the adapter can accommodate both fully automated workflows and carefully controlled user approval processes, depending on your application's needs.

Storage Backend Flexibility

The Contact Adapter requires a store implementation for persisting verification tokens and session data. While it's compatible with popular solutions like Redis and Vercel KV out of the box, the extensible ContactStore interface allows you to implement your own storage backend if needed. For development, a memory-based store is provided—though production applications should always use persistent storage to handle server restarts and distributed deployments.

Complete Working Example

To help developers get started quickly, we've included a complete working example in the Node SDK repository demonstrating the entire authentication flow. The example showcases sign-in, verification, session management, and how to integrate authenticated contacts with ChatBotKit's conversation system—providing a solid foundation for building your own contact-based applications.

Choosing the Right Adapter

With two authentication adapters now available, developers can choose the approach that best fits their use case:

The Partner Adapter remains ideal for SaaS platforms, white-label solutions, and scenarios requiring complete user isolation with separate sub-accounts. The new Contact Adapter excels in chat applications, customer support systems, and community platforms where shared resources and simpler billing are advantageous.

Both adapters eliminate the complexity of building authentication infrastructure from scratch, letting you focus on creating exceptional user experiences rather than managing login flows and security concerns.

Getting Started

The Contact Adapter is available now in the @chatbotkit/nextauth package. Install it alongside NextAuth.js:

Then configure your NextAuth setup with the Contact Adapter:

For complete documentation, code examples, and best practices, visit the Node SDK repository and explore the contact-auth example. We're excited to see what you build with this new authentication option!