Makerkit 2.11.0: Building Better Authentication Experiences

Authentication is often the first interaction users have with your SaaS product. Get it wrong, and you'll face frustrated users and endless support tickets. Get it right, and you create a smooth onboarding experience that sets the tone for everything that follows.

Makerkit 2.11.0 introduces four major improvements to authentication and billing that address the most common pain points we've seen developers struggle with. Let's dive into what's new and why these features matter for your SaaS business.

The Problem with Traditional Authentication

Before we jump into the new features, let's talk about the real-world problems these updates solve:

• User Confusion: Users forget how they originally signed up. Did they use Google? Their work email? That GitHub account they barely remember?
• Email Delivery Issues: Magic links get intercepted by corporate email scanners, especially with Outlook and Hotmail accounts. Users click expired links and assume your app is broken.
• Support Overhead: "I can't log in" tickets pile up. Users create duplicate accounts. Billing questions about discontinued plans create confusion.
• Technical Debt: Legacy customers stay on old plans, but removing those plans from your codebase breaks their billing pages.

These aren't edge cases—they're everyday realities that affect user retention and support costs. Here's how Makerkit 2.11.0 addresses each one.

Identity Linking: One User, Multiple Login Methods

What It Does

Identity linking allows users to connect multiple authentication methods to a single account. Someone can sign up with their email, then later link their Google and GitHub accounts—all pointing to the same user profile and data.

Why This Matters

Think about your own online accounts. You probably have services where you've used different login methods over time. Maybe you started with email/password, then switched to Google for convenience, then used GitHub for a work project. Without identity linking, each method creates a separate account.

Here's what typically happens without identity linking:

1. User signs up with john@company.com and password
2. Months later, they try to log in with Google using the same email
3. System creates a new account instead of recognizing the existing one
4. User loses access to their data and gets frustrated
5. Support ticket gets created

With identity linking:

1. User signs up with john@company.com and password
2. Later, they can link their Google account to the same profile
3. They can now log in using either method
4. All data stays connected to one account
5. No confusion, no support tickets

Implementation Details

Enabling identity linking requires both client and server configuration:

# Environment variable
NEXT_PUBLIC_AUTH_IDENTITY_LINKING=true

You also need to enable it in your Supabase Console under Authentication > Settings. This ensures the backend properly handles the account linking process.

The feature works with all supported authentication methods:

• Email/password
• Magic links
• OTP codes
• OAuth providers (Google, GitHub, etc.)

Users can link accounts through their profile settings, and the UI clearly shows which methods are connected to their account.

OTP Sign-In: Solving the Magic Link Problem

The Magic Link Problem

Magic links seem like a great user experience—no passwords to remember, just click a link in your email. But they have a fatal flaw: email security scanners.

Corporate email systems (especially Outlook/Hotmail) automatically scan incoming emails for security threats. When they find a clickable link, they often visit it automatically to check if it's safe. This "clicks" your magic link before the user ever sees their email.

By the time the user checks their inbox and clicks the link, it's already been used and expired. They see an error message and assume your app is broken.

How OTP Solves This

One-time passwords (OTP) can't be "clicked" by email scanners because they're just numbers that users need to manually enter. The user receives a 6-digit code, types it into your app, and authentication succeeds reliably.

When to Use OTP vs Magic Links

Use OTP when:

• Your users primarily use corporate email (Outlook, Exchange)
• You're targeting enterprise customers
• You want maximum reliability
• Mobile usage is high (typing 6 digits is easier than switching between apps)

Use Magic Links when:

• Consumer-focused product
• Users primarily use Gmail, Apple Mail, or other personal email services
• You want the smoothest possible experience
• Desktop usage is primary

Implementation

Enabling OTP is straightforward:

NEXT_PUBLIC_AUTH_OTP=true
NEXT_PUBLIC_AUTH_PASSWORD=false  # Optional: disable password auth

You'll also need to update your email template in Supabase Dashboard. OTP and magic links share the same email template, so use the provided otp.html template instead of magic-link.html.

The OTP flow works like this:

1. User enters their email address
2. System sends a 6-digit code to their email
3. User enters the code in your app
4. Authentication succeeds and they're logged in

The codes expire after a reasonable time window (typically 5-10 minutes), and users can request a new code if needed.

Smart Sign-In Hints: Preventing Account Confusion

The Duplicate Account Problem

Users forget they already have accounts. They try to sign up again with the same email and get a confusing "email already taken" error. This leads to:

• Abandoned sign-ups
• Support tickets asking "how do I recover my old account?"
• Users creating accounts with different email addresses
• Fragmented user data and billing

The Psychology Behind It

The key insight is that users don't always remember having an account, especially if they signed up months ago and never fully onboarded. By being helpful rather than accusatory, you:

• Reduce cognitive load on users
• Prevent them from bouncing off your sign-up flow
• Guide them toward successful authentication
• Reduce support ticket volume

Technical Implementation

This feature works automatically—no configuration needed. The system checks email addresses during sign-up and provides contextual hints when appropriate.

The implementation is smart enough to:

• Detect existing accounts across all authentication methods
• Suggest the most recent sign-in method used
• Preserve the user's intent to access your application
• Maintain security by not revealing sensitive account information

Legacy Plans Support: Managing Discontinued Products

The Legacy Plan Challenge

Every SaaS business eventually faces this scenario: you want to discontinue a pricing plan but keep existing customers on it. Maybe you're simplifying your pricing, discontinuing a feature, or repositioning your product.

The challenge is technical: if you remove the plan from your codebase, existing customers' billing pages break. They can't see what they're paying for, when it renews, or how to manage their subscription.

Two Flexible Solutions

Makerkit 2.11.0 provides two approaches for handling legacy plans:

Option 1: Hidden Flag

Mark plans as "hidden" to remove them from your pricing page while keeping them functional for existing subscribers:

const legacyPlan = {
  id: 'legacy-pro-plan',
  name: 'Legacy Pro Plan',
  hidden: true,  // Removes from pricing page
  // ... other plan details
}

This approach gives you full control over the plan presentation and allows you to provide detailed information to existing subscribers.

Option 2: Automatic Fallback

If you completely remove a plan from your system, Makerkit automatically fetches plan details from your payment provider (Stripe, Paddle, etc.):

// Plan removed from your config entirely
// System automatically fetches details from Stripe/Paddle

This works best for simple, flat-rate plans. For complex pricing structures with multiple line items, the hidden flag approach gives you more control over the user experience.

Configuration and Environment Variables

All these features are controlled through environment variables, making them easy to enable/disable without code changes:

# Identity Linking
NEXT_PUBLIC_AUTH_IDENTITY_LINKING=true
# OTP Authentication
NEXT_PUBLIC_AUTH_OTP=true
NEXT_PUBLIC_AUTH_MAGIC_LINK=false
NEXT_PUBLIC_AUTH_PASSWORD=false
# Additional auth options
NEXT_PUBLIC_DISPLAY_TERMS_AND_CONDITIONS_CHECKBOX=true
NEXT_PUBLIC_PASSWORD_REQUIRE_UPPERCASE=true
NEXT_PUBLIC_PASSWORD_REQUIRE_NUMBERS=true
NEXT_PUBLIC_PASSWORD_REQUIRE_SPECIAL_CHARS=true

The configuration is validated using Zod schemas, so you'll get clear error messages if something is misconfigured.

Real-World Impact

These features address measurable business problems:

• Reduced Support Volume: Fewer "I can't log in" and "where's my billing info" tickets means your team can focus on building features instead of answering repetitive questions.
• Higher Conversion Rates: Smart sign-in hints prevent users from abandoning your sign-up flow when they encounter confusion about existing accounts.
• Better User Retention: Identity linking and reliable authentication reduce friction that causes users to give up on your product.
• Cleaner Codebase: Legacy plan support lets you evolve your pricing without accumulating technical debt or breaking existing customer experiences.
• Enterprise Readiness: OTP support makes your product more suitable for corporate environments with strict email security policies.

How to Update

These features are available now in Makerkit 2.11.0. To update, use the following command in your project:

git pull upstream main

Looking Forward

Authentication and billing might seem like solved problems, but user expectations continue to evolve. Features like identity linking and OTP support are becoming table stakes for modern SaaS applications.

Makerkit 2.11.0 is available now. Check out the authentication configuration guide for detailed implementation instructions and best practices.