Announcing multi-factor authentication

Medusa now ships time-based one-time password (TOTP) multi-factor authentication as part of the core Auth Module.

This gives Medusa applications a first-class way to add authenticator-app based MFA for admin users, customers, or any custom actor type, without building a custom auth provider or relying on a hosted auth service.

MFA adds a second verification step after the first authentication factor. Once enabled, a successful login no longer returns a token directly. Instead, Medusa returns an MFA challenge that the user completes with a code from an app like 1Password, Authy, Google Authenticator, or Microsoft Authenticator.

Because MFA lives in the Auth Module, it works across auth providers and actor types. The same core flow can protect admin users signing into the dashboard, customers signing into a storefront, or custom actors in your own application.

How MFA works

Auth providers still handle the first factor.

For example, email/password verifies the user's credentials, GitHub verifies the OAuth callback, and a custom auth provider can continue to do its own authentication exactly as before.

After the first factor succeeds, Medusa checks whether the authenticated Copy to clipboardauth_identity has MFA enabled.

If MFA is not enabled, Medusa returns a token as usual.

If MFA is enabled, Medusa does not issue the token immediately. Instead, it creates a short-lived MFA challenge and returns it to the client:

123456789
{
  mfa_required: true
  mfa_challenge: {
    id: string
    methods: ("totp" | "recovery_code")[]
    expires_at: string
  }
}

The client then asks the user for a code from their authenticator app, or a recovery code, and verifies the challenge. Only after the challenge is verified does Medusa issue the final auth token.

This keeps MFA separate from auth providers: providers prove the first factor, while Medusa core decides whether a second factor is required before a token can be minted.

TOTP setup

TOTP is the initial MFA method supported by Medusa. During setup, Medusa creates a pending MFA factor and returns the setup details needed by an authenticator app:

12345678910
{
  "mfa": {
    "id": "string",
    "provider": "totp",
    "status": "pending"
  },
  "secret": "string",
  "otpauth_url": "string"
}

Applications can show the Copy to clipboardotpauth_url as a QR code, or let users copy the secret manually into their authenticator app.

The user then enters the code generated by the authenticator app. If the code is valid, Medusa marks the MFA factor as enabled.

Recovery codes

Medusa also includes recovery codes.

Recovery codes are one-time backup codes that can complete an MFA challenge if the user loses access to their authenticator app.

They are shown to the user once, hashed before storage, and consumed after use. Applications can let users generate a new set of recovery codes when needed.

Admin dashboard support

The Medusa Admin dashboard includes MFA setup and management out of the box.

Admin users can enable MFA from their profile, scan a QR code with an authenticator app, confirm setup with a TOTP code, and save recovery codes.

Using MFA in custom apps

Custom storefronts and applications can use the same core APIs.

The Auth Module exposes routes for:

• starting MFA setup
• verifying a pending MFA factor
• listing enabled MFA factors
• disabling MFA
• generating recovery codes
• verifying MFA challenges during login

The JS SDK exposes these operations under Copy to clipboardsdk.auth.mfa, so applications can implement the full flow without calling the routes manually.

Configuration

MFA is configured through the Auth Module options in Copy to clipboardmedusa-config.ts.

1234567891011121314151617
mfa: {
  encryption_key: process.env.AUTH_MFA_ENCRYPTION_KEY,
  challenge_ttl_seconds: 300,
  max_attempts: 5,
  recovery_code_count: 10,
  providers: [
    {
      id: "totp",
      options: {
        issuer: "My Medusa Store",
        digits: 6,
        period: 30,
      },
    },
  ],
}

The encryption key is used to encrypt TOTP secrets at rest. TOTP secrets need to be recoverable so Medusa can verify future codes, which means they cannot be hashed like passwords.

Recovery codes, on the other hand, are one-time secrets. Medusa stores them as hashes and never stores the raw values.

Security details

MFA in Medusa includes the core controls expected from an authenticator-app based setup:

• TOTP secrets are encrypted at rest.
• Recovery codes are hashed before storage.
• Login challenges are short-lived.
• Challenge verification has retry limits.
• Tokens are only issued after MFA succeeds.
• MFA lifecycle events can be used for audit logs and notifications.

Extending MFA

TOTP and recovery codes are built in, but the MFA implementation is provider-based.

That means Medusa can support additional second-factor methods in the future, and applications can build custom MFA providers that plug into the same challenge and verification flow.

Get started

MFA is available in the Medusa Auth Module.

Add the MFA options to your auth configuration, configure an encryption key, and use the Admin dashboard or JS SDK to enable authenticator-app based MFA in your Medusa application.

Learn more in our new MFA section in our Docs.