Supertokens

SuperTokens authentication provider plugin for Medusa v2. Enables OAuth2/OpenID Connect authentication using SuperTokens as the identity provider.

npm install @xbstracts/medusa-supertokens

@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

1┌─────────────────┐     ┌─────────────────────┐     ┌─────────────────┐
2│   Storefront    │     │   hisher-auth       │     │ SuperTokens Core│
3│  (Next.js)      │     │   (Backend API)     │     │   (Database)    │
4│  localhost:3000 │     │   localhost:4002    │     │  localhost:3567 │
5└────────┬────────┘     └──────────┬──────────┘     └────────┬────────┘
       │                         │                          │
       │  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

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

Configuration

1. Configure Medusa

Add the plugin to your :

1import { defineConfig } from '@medusajs/framework/utils';
2
3module.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: {},
  },
],
45});

2. Environment Variables

Add these to your file:

1# SuperTokens Configuration
2SUPERTOKENS_CORE_URL=http://localhost:3567
3SUPERTOKENS_API_DOMAIN=http://localhost:4002
4SUPERTOKENS_API_BASE_PATH=/auth
5SUPERTOKENS_API_KEY=your-api-key
6SUPERTOKENS_CALLBACK_URL=http://localhost:3000/auth/callback

Usage

Authentication Flow

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

API Endpoints

Authenticate with session token:

1POST /auth/customer/supertokens
2Content-Type: application/json
3
4{
5  "access_token": "<supertokens-session-access-token>"
6}

Or via Authorization header:

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

Response (success):

1{
2  "token": "<medusa-jwt-token>"
3}

Legacy Profile Integration

On every authentication, the plugin calls 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

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

Connection refused errors

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

License

MIT

Supertokens

SuperTokens authentication provider plugin for Medusa v2. Enables OAuth2/OpenID Connect authentication using SuperTokens as the identity provider.

npm install @xbstracts/medusa-supertokens

@patiparnne/medusa-supertokens

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

1┌─────────────────┐     ┌─────────────────────┐     ┌─────────────────┐
2│   Storefront    │     │   hisher-auth       │     │ SuperTokens Core│
3│  (Next.js)      │     │   (Backend API)     │     │   (Database)    │
4│  localhost:3000 │     │   localhost:4002    │     │  localhost:3567 │
5└────────┬────────┘     └──────────┬──────────┘     └────────┬────────┘
       │                         │                          │
       │  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

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

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

Configuration

1. Configure Medusa

Add the plugin to your :

1import { defineConfig } from '@medusajs/framework/utils';
2
3module.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: {},
  },
],
45});

2. Environment Variables

Add these to your file:

1# SuperTokens Configuration
2SUPERTOKENS_CORE_URL=http://localhost:3567
3SUPERTOKENS_API_DOMAIN=http://localhost:4002
4SUPERTOKENS_API_BASE_PATH=/auth
5SUPERTOKENS_API_KEY=your-api-key
6SUPERTOKENS_CALLBACK_URL=http://localhost:3000/auth/callback

Usage

Authentication Flow

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

API Endpoints

Authenticate with session token:

1POST /auth/customer/supertokens
2Content-Type: application/json
3
4{
5  "access_token": "<supertokens-session-access-token>"
6}

Or via Authorization header:

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

Response (success):

1{
2  "token": "<medusa-jwt-token>"
3}

Legacy Profile Integration

On every authentication, the plugin calls 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

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

Connection refused errors

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

License

MIT

Supertokens

@patiparnne/medusa-supertokens

Features

Architecture Overview

Port Configuration (His & Her Project)

Prerequisites

Installation

Configuration

1. Configure Medusa

2. Environment Variables

Usage

Authentication Flow

API Endpoints

Legacy Profile Integration

Options Reference

Troubleshooting

"Invalid or expired session token"

"Failed to retrieve user information"

Customer created with generated email instead of real email

Connection refused errors

Related Documentation

License

More in this category

Passwordless

Keycloak

WebAuthn

Supertokens

@patiparnne/medusa-supertokens

Features

Architecture Overview

Port Configuration (His & Her Project)

Prerequisites

Installation

Configuration

1. Configure Medusa

2. Environment Variables

Usage

Authentication Flow

API Endpoints

Legacy Profile Integration

Options Reference

Troubleshooting

"Invalid or expired session token"

"Failed to retrieve user information"

Customer created with generated email instead of real email

Connection refused errors

Related Documentation

License

More in this category

Passwordless

Keycloak

WebAuthn