A Medusa v2 admin API 401 right after a login that returned 200 is almost always one of five things: the login went to the wrong actor type (customer instead of user), the session cookie is blocked because it is Secure on a plain-HTTP localhost, a reverse proxy tells Medusa the request is HTTP, CORS or fetch credentials stop the cookie on a cross-origin admin app, or you are sending a publishable API key to /admin/*, where only a JWT or an admin session cookie works. Each has its own signature, and none needs a change to your business logic.
The pattern is common when moving from v1: the login route succeeds, the next admin call returns 401, and the developer assumes the password is wrong. It rarely is. I run Medusa v2 development work at MithTech, a team of Frappe specialists in Bengaluru who build mainly on Frappe and Medusa. This is the order we check things in on a Medusa v2 auth problem. Code and config below were checked against the Medusa source at v2.21.2 on 12 October 2026.
The five causes at a glance
| Signature | First check | ||
|---|---|---|---|
| 1 | Wrong actor type in the auth URL | Login to /auth/customer/emailpass succeeds, /admin/* returns 401 | Confirm the login URL contains /auth/user/, not /auth/customer/ |
| 2 | Secure cookie on plain-HTTP localhost | DevTools → Application → Cookies: no connect.sid after login | Look for Secure on the Set-Cookie header from /auth/session |
| 3 | Reverse proxy hides HTTPS | Login works through a port-forward, fails through the public URL | Confirm the request reaching Medusa carries X-Forwarded-Proto: https |
| 4 | Cross-origin fetch without credentials | No cookie attached to the admin request; CORS errors in the console | Check credentials: "include" on fetch and the server's CORS lists |
| 5 | Publishable key on /admin/* | 401 on the admin call, publishable key fine on /store | Confirm the request uses a JWT or a session, not x-publishable-api-key |
Are you authenticating against the right actor type?
Answer
Medusa v2 separates admin users and customers into two actor types with two auth URL prefixes. POST /auth/user/emailpass returns a JWT for /admin/* routes; POST /auth/customer/emailpass returns a JWT for customer routes such as /store/customers/me. A token for one is a 401 on the other. Check that the URL says user, not customer.
The v2 auth pattern:
Admin user login → JWT for /admin/*
Storefront (shopper) login → JWT for /store/customers/me
With the JS SDK, the actor type is the first argument to login:
// Admin
await sdk.auth.login("user", "emailpass", { email, password })
// Storefront
await sdk.auth.login("customer", "emailpass", { email, password })
If you copied from a storefront tutorial into an admin app, the actor type may be wrong. The JS SDK auth overview documents the full signature.
Is the secure-cookie flag blocking localhost?
The clearest symptom: POST /auth/session returns 200 OK, DevTools → Network shows Set-Cookie: connect.sid=...; Secure; HttpOnly, and DevTools → Application → Cookies shows no connect.sid for localhost.
The cause: medusa start sets NODE_ENV=production if you haven't set it, and in production (or NODE_ENV=staging) Medusa's Express loader sets the session cookie to secure: true, sameSite: "lax". In any other environment it sets secure: false. Browsers drop a Secure cookie on plain HTTP, so the login succeeds on the server, nothing is stored in the browser, and the next admin request carries no credential.
Two fixes:
A. Use medusa develop for local work. It runs with NODE_ENV=development, so the cookie is not Secure. The trap is running medusa start locally "to test production" and then debugging a phantom auth issue.
B. Override the cookie for a local production build only. cookieOptions sits directly under projectConfig (not under http) and is merged over Medusa's defaults:
export default defineConfig({
projectConfig: {
cookieOptions: {
secure: false, // local HTTP only: never ship this to production
sameSite: "lax",
},
// ... rest of config
},
})
Restart the server and connect.sid will be stored on localhost.
To test real production behaviour locally, put HTTPS in front with a tunnel (ngrok or Cloudflare Tunnel) so the browser sees an https:// URL. Then the secure cookie works and you are testing what you will deploy.
Is your reverse proxy hiding HTTPS from Medusa?
Issue #14550 reports this on Medusa v2.11.0 behind an NGINX Ingress on Kubernetes: login returns 200, the session endpoint returns 200, a connect.sid cookie is sent, and the next /admin/users/me returns 401. Direct access to the pod via kubectl port-forward works. The issue was closed in January 2026 after users posted configuration workarounds; Medusa's code did not change.
What Medusa does: its Express loader sets trust proxy to 1 (it trusts one proxy hop) and creates the session with proxy: true. A secure cookie is only set when the request counts as HTTPS, and behind a proxy that decision comes from X-Forwarded-Proto. There is no trustProxy option in medusa-config.ts to switch on; the work is in the proxy.
What to check:
- Single proxy that terminates TLS (NGINX, Caddy, Traefik): it must pass
X-Forwarded-Proto: https. On a plain NGINX in front of a container, addproxy_set_header X-Forwarded-Proto $scheme;(orhttps) inside thelocationblock. Caddy and Traefik set the header themselves when they terminate TLS. - Two hops (a CDN or cloud load balancer in front of NGINX, Traefik or another load balancer): the inner hop may see plain HTTP and append
http, so Medusa sees the request as HTTP. In #14550 a user behind CloudFront and an AWS ALB hit exactly this; their workaround, posted in the thread, was a Medusa middleware that forces the protocol to HTTPS on the auth and admin routes. Where you control the inner proxy, make it pass on the outerhttpsinstead of its own scheme. - NGINX Ingress behind a cloud load balancer that terminates TLS: the controller only passes incoming
X-Forwarded-*headers on whenuse-forwarded-headers: "true"is set in its ConfigMap.
See the Coolify + Hetzner Medusa deploy guide for a full self-hosted setup.
Is CORS or fetch keeping the cookie off cross-origin requests?
If your admin app runs on admin.example.com and the API on api.example.com, the requests are cross-origin. fetch sends cookies only to its own origin unless you ask for more. Two things must be true.
Client side: send credentials.
fetch("https://api.example.com/admin/users/me", {
credentials: "include", // without this, cookies are not sent cross-origin
headers: { "Content-Type": "application/json" },
})
With the JS SDK, set auth.type: "session" and auth.fetchCredentials: "include". In session mode sdk.auth.login also calls /auth/session for you:
const sdk = new Medusa({
baseUrl: "https://api.example.com",
auth: {
type: "session",
fetchCredentials: "include",
},
})
Server side: allow the origin. In medusa-config.ts, list the exact origins in projectConfig.http. Browsers reject a wildcard * origin on a request with credentials, so name each one:
projectConfig: {
http: {
adminCors: "https://admin.example.com,http://localhost:5173",
storeCors: "https://shop.example.com",
authCors: "https://admin.example.com,https://shop.example.com",
},
},
authCors must include every origin that calls /auth/*. A common miss: the admin app moves to a new domain and only adminCors is updated. A storefront calling /store/* from another origin needs the same care with storeCors; see the Medusa + Razorpay India setup guide.
Are you sending a publishable key on an /admin/* route?
Publishable API keys in Medusa v2 scope /store/* requests to sales channels. They are not admin credentials. If code carried over from v1 does this:
// This works on /store/products (v2 requires it there):
fetch("/store/products", {
headers: { "x-publishable-api-key": PK },
})
// This does NOT work: /admin routes need a JWT or a session cookie
fetch("/admin/products", {
headers: { "x-publishable-api-key": PK }, // not an admin credential; response is 401
})
Use the right credential for the route family. For /admin/*, send Authorization: Bearer <jwt> (from /auth/user/emailpass) or make sure the session cookie is sent. For /store/*, keep sending x-publishable-api-key.
What is the correct end-to-end auth flow?
0 of 5 steps done
Tick a step’s number when it is done; the ticks stay on this device.
Choose your auth model up front: JWT or session
JWT is stateless and suits mobile apps, server-to-server code and clients on another origin: the client stores the token and sends it as Authorization: Bearer. Session is stateful and suits a browser-based admin app: the server sets a cookie the browser sends on its own. Don't mix the two on one client.
For the JWT flow: call POST /auth/user/emailpass and keep the token
POST https://api.example.com/auth/user/emailpass with { email, password } in the JSON body returns { token: "<jwt>" }. Store it (the JS SDK can keep it in local storage or memory for you) and send it as Authorization: Bearer <jwt> on every /admin/* request.
For the session flow: call /auth/user/emailpass, then POST /auth/session
Session auth takes a second call. POST /auth/user/emailpass returns a JWT. Then POST /auth/session with that JWT in the Authorization: Bearer header makes Medusa set the session cookie on the response. From then on the cookie carries the session; you don't send the JWT again.
Check the cookie survived the round trip
In DevTools → Application → Cookies for the API domain, look for connect.sid (or the name set in sessionOptions.name). If it is missing after a 200 from /auth/session, walk causes 2, 3 and 4 in order: the localhost secure flag, the proxy headers, then CORS and credentials.
Test with GET /admin/users/me
This is the smoke test. A 200 with your user object confirms the whole chain: login, session or JWT, the cookie or header reaching the server, and CORS. A 401 here means no valid credential reached the server.
FAQ
Why does my admin login return 200 but the next admin call returns 401?
Because a 200 from login does not mean a session exists. In JWT mode, login returns a token you must attach to every later request as Authorization: Bearer <jwt>. In session mode it is two calls: /auth/user/emailpass gives you a JWT, and POST /auth/session turns it into a cookie. If you stopped after the first call, no admin credential was ever stored.
Should I use JWT or session auth for a Medusa v2 admin?
Session, if the admin runs in a browser on a stable origin: once configured, the cookie handling is invisible. JWT, if the admin is a mobile app, a single-page app on another origin, or a headless integration where the client should manage the token itself. The JS SDK auth overview covers both.
Do I need a publishable API key for admin routes on v2?
No. Publishable API keys are for /store/* routes, where they scope the request to sales channels. /admin/* routes are authenticated with a JWT or session cookie belonging to an admin user. A publishable key header on an admin request authenticates nothing.
Can the v2 admin API return 401 on a JWT that used to work?
Yes, once it expires. Admin JWTs last 24 hours unless you set projectConfig.http.jwtExpiresIn. If admin calls work after login and start returning 401 later, re-authenticate. Session cookies expire on their own clock: projectConfig.sessionOptions.ttl, 10 hours by default.
Comments & ratings
No comments yet. Start a new discussion.
Manoj · Published on 9 August 2026
Worked with us? Leave a Google review