medusa-security

name	medusa-security
description	Secure Medusa v2 applications — authentication strategies, API key types (publishable vs secret), CORS configuration, JWT and cookie secrets, admin vs store auth, and session management. Use when configuring security.
allowed-tools	Read, Write, Edit, Bash, Grep, Glob, WebSearch, WebFetch

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:

Aspect	Admin Auth	Store Auth
Actor type	user	customer
API scope	/admin/* routes	/store/* routes
Default provider	emailpass	emailpass
Session cookie	Admin session cookie	Store session cookie
API key support	Secret API key (Bearer)	Publishable API key (header)
JWT usage	Admin JWT token	Customer JWT token
Middleware	authenticate("user", ...)	authenticate("customer", ...)

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

Key Type	Header	Purpose	Visibility
Publishable	x-publishable-api-key	Storefront API access, scopes to sales channels	Safe for client-side
Secret	Authorization: Bearer <key>	Admin API access, full permissions	Server-side only

• 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:

Setting	Purpose	Example
storeCors	Allowed origins for Store API	http://localhost:8000
adminCors	Allowed origins for Admin API	http://localhost:9000
authCors	Allowed origins for Auth routes	http://localhost:8000,http://localhost:9000

• 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

Secret	Environment Variable	Purpose
Cookie secret	COOKIE_SECRET	Signs session cookies
JWT secret	JWT_SECRET	Signs JSON Web Tokens
Admin JWT	Configured per auth provider	Admin token signing
Store JWT	Configured per auth provider	Customer token signing

• 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"

Middleware Function	Actor Type	Use Case
authenticate("user", ...)	Admin user	Admin-only routes
authenticate("customer", ...)	Customer	Store auth-required routes
authenticate("user", ["bearer","session"])	Admin	Multiple auth strategies

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

Method	Purpose
authenticate()	Verify identity (login)
register()	Create new identity
validateCallback()	Handle OAuth redirect callbacks

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.