Medusa Security

Medusa v2 Security

Before writing code

Fetch live docs:

1. Web-search site:docs.medusajs.com authentication for auth strategies and API key setup
2. Web-search site:docs.medusajs.com api key publishable secret for API key types
3. Web-search site:docs.medusajs.com CORS configuration for cross-origin resource sharing
4. Fetch https://docs.medusajs.com/learn/fundamentals/api-routes/middlewares for middleware and auth config
5. Web-search site:docs.medusajs.com medusa-config auth providers for auth provider registration

Authentication Architecture

Admin vs Store Authentication

Medusa v2 separates admin and storefront authentication into distinct flows:

Auth Provider System

Auth Module
├── emailpass    — email + password (default)
├── google       — OAuth 2.0 via Google
├── github       — OAuth 2.0 via GitHub
└── custom       — implement AbstractAuthModuleProvider

Auth providers are registered in medusa-config.ts under the auth module configuration. Each provider handles a specific identity verification strategy.

API Key Types

• Publishable keys are created in the admin dashboard and tied to sales channels
• Secret keys grant admin-level access and must never be exposed to browsers
• Store API routes require a publishable key header for sales channel scoping

CORS Configuration

Configure CORS in medusa-config.ts under projectConfig:

• Use comma-separated strings or regex patterns for multiple origins
• In production, restrict to exact domains — never use * wildcard
• authCors must include both storefront and admin origins

JWT and Cookie Secrets

Secret Configuration

• Both COOKIE_SECRET and JWT_SECRET must be set in production
• Use cryptographically random strings (minimum 32 characters)
• Rotate secrets by updating env vars and restarting the server

Session Management

Sessions are managed via HTTP-only cookies with configurable options:

• Session store — in-memory by default; use Redis for production
• Cookie flags — httpOnly, secure, sameSite, maxAge
• Session TTL — configurable expiration; defaults vary by auth scope
• Redis session store ensures sessions survive server restarts and work across multiple instances

API Route Authentication

Middleware Configuration

Apply auth middleware in src/api/middlewares.ts:

// Fetch live docs for authenticate() middleware
// signature and actor type options
import { authenticate } from "@medusajs/medusa"

Auth Scopes on Custom Routes

• Admin routes: place in src/api/admin/ — auto-protected
• Store routes: place in src/api/store/ — require publishable key
• Custom routes: manually apply authenticate() middleware

Auth Provider Implementation

Custom auth providers extend AbstractAuthModuleProvider:

// Fetch live docs for AbstractAuthModuleProvider
// methods: authenticate, register, validateCallback

Security Hardening Checklist

Environment Variables

• Set unique COOKIE_SECRET and JWT_SECRET (never use defaults)
• Use DATABASE_URL with SSL mode for PostgreSQL connections
• Store secrets in environment variables, never in source code

Network and Transport

• Enforce HTTPS in production for all API communication
• Restrict CORS origins to exact production domains
• Use secure: true and sameSite: "strict" on cookies in production

API Keys and Access

• Create separate publishable keys per sales channel
• Rotate secret API keys on a regular schedule
• Audit admin user accounts and remove unused access
• Use the principle of least privilege for API key scoping

Session and Token Security

• Use Redis as session store in production (not in-memory)
• Set appropriate session TTL values (short for admin, configurable for store)
• Implement token refresh logic in storefronts

Best Practices

• Auth provider selection — use emailpass for standard flows; add OAuth providers for social login; register providers in medusa-config.ts under the auth module
• Key management — publishable keys are public and safe for client bundles; secret keys must only live on the server; never log or commit API keys
• CORS discipline — always set storeCors, adminCors, and authCors explicitly; test CORS headers before deploying; avoid wildcard origins in production
• Cookie security — enable httpOnly, secure, and sameSite flags; use Redis-backed sessions for multi-instance deployments; set reasonable TTLs

Fetch the Medusa authentication and security documentation for exact provider registration syntax, middleware options, and cookie configuration before implementing.