From medusa-commerce
Secures Medusa v2 apps: auth strategies for admin/store, publishable/secret API keys, CORS config, JWT/cookie secrets, and session management.
npx claudepluginhub orcaqubits/agentic-commerce-skills-plugins --plugin medusa-commerceThis skill is limited to using the following tools:
**Fetch live docs**:
Generates design tokens/docs from CSS/Tailwind/styled-components codebases, audits visual consistency across 10 dimensions, detects AI slop in UI.
Records polished WebM UI demo videos of web apps using Playwright with cursor overlay, natural pacing, and three-phase scripting. Activates for demo, walkthrough, screen recording, or tutorial requests.
Delivers idiomatic Kotlin patterns for null safety, immutability, sealed classes, coroutines, Flows, extensions, DSL builders, and Gradle DSL. Use when writing, reviewing, refactoring, or designing Kotlin code.
Fetch live docs:
site:docs.medusajs.com authentication for auth strategies and API key setupsite:docs.medusajs.com api key publishable secret for API key typessite:docs.medusajs.com CORS configuration for cross-origin resource sharinghttps://docs.medusajs.com/learn/fundamentals/api-routes/middlewares for middleware and auth configsite:docs.medusajs.com medusa-config auth providers for auth provider registrationMedusa 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 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.
| 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 |
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 |
* wildcardauthCors must include both storefront and admin origins| 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 |
COOKIE_SECRET and JWT_SECRET must be set in productionSessions are managed via HTTP-only cookies with configurable options:
httpOnly, secure, sameSite, maxAgeApply 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 |
src/api/admin/ — auto-protectedsrc/api/store/ — require publishable keyauthenticate() middlewareCustom 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 |
COOKIE_SECRET and JWT_SECRET (never use defaults)DATABASE_URL with SSL mode for PostgreSQL connectionssecure: true and sameSite: "strict" on cookies in productionemailpass for standard flows; add OAuth providers for social login; register providers in medusa-config.ts under the auth modulestoreCors, adminCors, and authCors explicitly; test CORS headers before deploying; avoid wildcard origins in productionhttpOnly, secure, and sameSite flags; use Redis-backed sessions for multi-instance deployments; set reasonable TTLsFetch the Medusa authentication and security documentation for exact provider registration syntax, middleware options, and cookie configuration before implementing.