@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

┌─────────────────┐     ┌─────────────────────┐     ┌─────────────────┐
│   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               │
         │                    │                                     │
         │                    │  5. Verify token via /profile/      │
         │                    │     verify-token (hisher-auth)      │
         │                    │  6. Get user info & metadata        │
         │                    │  7. Create/retrieve auth identity   │
         │                    └─────────────────────────────────────┘
         │                                      │
         │  8. Medusa JWT token                 │
         │ <────────────────────────────────────┘

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

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

Configuration

1. Configure Medusa

Add the plugin to your medusa-config.ts:

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",
              
              // API base path (default: '/auth')
              apiBasePath: process.env.SUPERTOKENS_API_BASE_PATH || "/auth",
              
              // SuperTokens Core API key (if configured)
              apiKey: process.env.SUPERTOKENS_API_KEY,
              
              // Callback URL for redirects (your storefront)
              callbackUrl: process.env.SUPERTOKENS_CALLBACK_URL || "http://localhost:3000/auth/callback",
              
              // Require email verification (default: false)
              verifyEmail: false,
            },
          },
        ],
      },
    },
  ],
  plugins: [
    // SuperTokens plugin - provides /store/auth/supertokens route for customer creation
    {
      resolve: '@patiparnne/medusa-supertokens',
      options: {},
    },
  ],
});

2. Environment Variables

Add these to your .env file:

# 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 POST /auth/customer/supertokens with the token
5. Profile enriched: Plugin calls /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:

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

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

Or via Authorization header:

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

Response (success):

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

Legacy Profile Integration

On every authentication, the plugin calls /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 [email protected])
• Customer first_name and last_name are populated
• Legacy member_id is preserved for reference

Options Reference

| Option | Type | Required | Default | Description | |--------|------|----------|---------|-------------| | coreUrl | string | Yes | - | SuperTokens Core URL (e.g., http://localhost:3567) | | apiDomain | string | Yes | - | hisher-auth Backend API URL (e.g., http://localhost:4002) | | apiBasePath | string | No | /auth | API base path for SuperTokens endpoints | | apiKey | string | No | - | SuperTokens Core API key (for direct Core access) | | callbackUrl | string | No | - | Redirect URL after login (storefront callback) | | verifyEmail | boolean | No | false | 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 /profile/verify-token returns metadata with email

Connection refused errors

• Verify coreUrl is correct and SuperTokens Core is running
• Verify apiDomain is correct and hisher-auth backend is running
• Check network/firewall settings

Related Documentation

• SuperTokens Documentation
• Medusa Auth Module

License

MIT