Skip to main content

Commerce

Medusa v2 Admin API Returns 401: The Five Real Causes (2026)

Login returns 200, GET /admin/users/me returns 401. Five causes: wrong actor type, secure cookie on localhost, proxy headers, CORS, publishable keys.

Updated 12 Oct 202611 min readBy ManojFirst published 9 Aug 2026

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

SignatureFirst check
1Wrong actor type in the auth URLLogin to /auth/customer/emailpass succeeds, /admin/* returns 401Confirm the login URL contains /auth/user/, not /auth/customer/
2Secure cookie on plain-HTTP localhostDevTools → Application → Cookies: no connect.sid after loginLook for Secure on the Set-Cookie header from /auth/session
3Reverse proxy hides HTTPSLogin works through a port-forward, fails through the public URLConfirm the request reaching Medusa carries X-Forwarded-Proto: https
4Cross-origin fetch without credentialsNo cookie attached to the admin request; CORS errors in the consoleCheck credentials: "include" on fetch and the server's CORS lists
5Publishable key on /admin/*401 on the admin call, publishable key fine on /storeConfirm 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:

TypeScript
// 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.

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:

TypeScript
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, add proxy_set_header X-Forwarded-Proto $scheme; (or https) inside the location block. 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 outer https instead of its own scheme.
  • NGINX Ingress behind a cloud load balancer that terminates TLS: the controller only passes incoming X-Forwarded-* headers on when use-forwarded-headers: "true" is set in its ConfigMap.

See the Coolify + Hetzner Medusa deploy guide for a full self-hosted setup.

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.

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

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

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

TypeScript
// 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.

Live demo

Your next step

Medusa v2 admin API returning 401 on a fresh login?

Sales and orders

An online order, start to finish

5 screens · about 8 min · you end with a payment recorded

See it live

Sales OrderTo deliver and bill

The customer's confirmed order: who it's for, the items at their price list and when it's due.

Customer
A demo customer
Prices
From their price list

Mith Demo Traders · demo company

Commerce

Now see what a store you own would look like

How we build and run Medusa storefronts and B2B portals connected to ERPNext, and when staying on a hosted platform is the better call.

Comments & ratings

No comments yet. Start a new discussion.

0

Manoj · Published on 9 August 2026

Worked with us? Leave a Google review

Questions about this? Talk to the team.

Book a 30-minute Google Meet, WhatsApp us, or send a message. The engineer who works on this replies.

Send us a message

Your details go to our team's CRM and are used only to reply.