SuperTokens Authentication

@patiparnne/medusa-supertokens

A Medusa v2 authentication provider plugin that enables session-based authentication using SuperTokens as the identity provider. Compatible with SuperTokens free tier (no OAuth2 license required).

Features

• Direct session token verification with SuperTokens Core
• Works with SuperTokens free tier (no paid features required)
• Supports all SuperTokens authentication methods (Email/Password, Passwordless/OTP, Social Login)
• Legacy CRM profile integration (refreshes profile data on every auth)
• Email verification enforcement (optional)
• Seamless integration with Medusa's auth module

Architecture Overview

1234567891011121314151617181920
┌─────────────────┐     ┌─────────────────────┐     ┌─────────────────┐
│   Storefront    │     │   hisher-auth       │     │ SuperTokens Core│
│  (Next.js)      │     │   (Backend API)     │     │   (Database)    │
│  localhost:3000 │     │   localhost:4002    │     │  localhost:3567 │
└────────┬────────┘     └──────────┬──────────┘     └────────┬────────┘
         │                         │                          │
         │  1. Login (OTP/Social)  │                          │
         │ ───────────────────────>│                          │
         │                         │  2. Create session       │
         │                         │ ────────────────────────>│
         │  3. Access token        │                          │
         │ <───────────────────────│                          │
         │                         │                          │
         │  4. POST /auth/customer/supertokens                │
         │ ─────────────────────────────────────┐             │
         │                                      │             │
         │                    ┌─────────────────┴─────────────┴─────┐
         │                    │        Medusa Backend               │
         │                    │        localhost:9000               │
         │                    │                                     │

Port Configuration (His & Her Project)

Service Port Description Storefront 3000 Next.js storefront app SuperTokens Core 3567 SuperTokens database/core service hisher-auth Backend 4002 SuperTokens backend API with OTP/profile routes hisher-auth Frontend 4003 SuperTokens demo UI (optional, for testing) Medusa Backend 9000 Medusa e-commerce API

Note: The hisher-auth frontend (port 4003) is a SuperTokens demo UI showing buttons like "Continue to Store", "Call API", "Logout". It's NOT an admin dashboard - it's designed for authenticated users to test the session. You don't need to run it for production.

Prerequisites

• Medusa v2.x
• SuperTokens Core running (self-hosted via Docker or managed)
• SuperTokens Backend API (hisher-auth) running
• Storefront configured to redirect to hisher-auth for login

Installation

123
npm install @patiparnne/medusa-supertokens
# or
yarn add @patiparnne/medusa-supertokens

Configuration

1. Configure Medusa

Add the plugin to your Copy to clipboardmedusa-config.ts:

1234567891011121314151617181920
import { defineConfig } from '@medusajs/framework/utils';

module.exports = defineConfig({
  // ... other config
  modules: [
    {
      resolve: "@medusajs/medusa/auth",
      options: {
        providers: [
          // SuperTokens Authentication Provider
          {
            resolve: "@patiparnne/medusa-supertokens/providers/supertokens-auth",
            id: "supertokens",
            options: {
              // SuperTokens Core URL (for direct session verification)
              coreUrl: process.env.SUPERTOKENS_CORE_URL || "http://localhost:3567",
              
              // hisher-auth Backend API URL (for profile enrichment)
              apiDomain: process.env.SUPERTOKENS_API_DOMAIN || "http://localhost:4002",
              

2. Environment Variables

Add these to your Copy to clipboard.env file:

123456
# SuperTokens Configuration
SUPERTOKENS_CORE_URL=http://localhost:3567
SUPERTOKENS_API_DOMAIN=http://localhost:4002
SUPERTOKENS_API_BASE_PATH=/auth
SUPERTOKENS_API_KEY=your-api-key
SUPERTOKENS_CALLBACK_URL=http://localhost:3000/auth/callback

Usage

Authentication Flow

1. User initiates login: Storefront redirects to hisher-auth login page
2. User authenticates: Via phone OTP, email/password, or social login (LINE, Google)
3. Session created: SuperTokens creates a session with access token
4. Token sent to Medusa: Storefront calls Copy to clipboardPOST /auth/customer/supertokens with the token
5. Profile enriched: Plugin calls Copy to clipboard/profile/verify-token on hisher-auth to get user data
6. Customer created/linked: Medusa creates or retrieves the customer
7. Medusa JWT returned: Storefront receives Medusa JWT for authenticated requests

API Endpoints

Authenticate with session token:

123456
POST /auth/customer/supertokens
Content-Type: application/json

{
  "access_token": "<supertokens-session-access-token>"
}

Or via Authorization header:

12
POST /auth/customer/supertokens
Authorization: Bearer <supertokens-session-access-token>

Response (success):

123
{
  "token": "<medusa-jwt-token>"
}

Legacy Profile Integration

On every authentication, the plugin calls Copy to clipboard/profile/verify-token on hisher-auth to:

• Verify the SuperTokens JWT token
• Fetch user info and metadata from SuperTokens
• Return any legacy CRM profile data stored in SuperTokens metadata

This ensures:

• Real email addresses from legacy CRM are used (instead of generated phone@domain.com)
• Customer first_name and last_name are populated
• Legacy member_id is preserved for reference

Options Reference

Option Type Required Default Description Copy to clipboardcoreUrl string Yes - SuperTokens Core URL (e.g., http://localhost:3567) Copy to clipboardapiDomain string Yes - hisher-auth Backend API URL (e.g., http://localhost:4002) Copy to clipboardapiBasePath string No Copy to clipboard/auth API base path for SuperTokens endpoints Copy to clipboardapiKey string No - SuperTokens Core API key (for direct Core access) Copy to clipboardcallbackUrl string No - Redirect URL after login (storefront callback) Copy to clipboardverifyEmail boolean No Copy to clipboardfalse Require email verification before allowing auth

Troubleshooting

"Invalid or expired session token"

• Ensure SuperTokens Core is running on port 3567
• Ensure hisher-auth backend is running on port 4002
• Check that the access token hasn't expired
• Verify the API key matches (if configured)

"Failed to retrieve user information"

• The user ID from the session doesn't exist in SuperTokens
• Check SuperTokens Core logs for errors
• Check hisher-auth backend logs

Customer created with generated email instead of real email

• Legacy profile data is fetched during OTP login flow
• Ensure the user logged in via phone OTP (which fetches legacy profile)
• Check that Copy to clipboard/profile/verify-token returns metadata with email

Connection refused errors

• Verify Copy to clipboardcoreUrl is correct and SuperTokens Core is running
• Verify Copy to clipboardapiDomain is correct and hisher-auth backend is running
• Check network/firewall settings

Related Documentation

• SuperTokens Documentation
• Medusa Auth Module

License

MIT