Auth Module

In this section of the documentation, you will find resources to learn more about the Auth Module and how to use it in your application.

Medusa has auth related features available out-of-the-box through the Auth Module. A module is a standalone package that provides features for a single domain. Each of Medusa's commerce features are placed in commerce modules, such as this Auth Module.

NoteLearn more about why modules are isolated in this documentation.

Auth Features#


How to Use the Auth Module#

In your Medusa application, you build flows around commerce modules. A flow is built as a Workflow, which is a special function composed of a series of steps that guarantees data consistency and reliable roll-back mechanism.

You can build custom workflows and steps. You can also re-use Medusa's workflows and steps, which are provided by the @medusajs/medusa/core-flows package.

For example:

src/workflows/authenticate-user.ts
1import { 2  createWorkflow, 3  WorkflowResponse,4  createStep,5  StepResponse,6} from "@medusajs/framework/workflows-sdk"7import { Modules, MedusaError } from "@medusajs/framework/utils"8import { MedusaRequest } from "@medusajs/framework/http"9import { AuthenticationInput } from "@medusajs/framework/types"10
11type Input = {12  req: MedusaRequest13}14
15const authenticateUserStep = createStep(16  "authenticate-user",17  async ({ req }: Input, { container }) => {18    const authModuleService = container.resolve(Modules.AUTH)19
20    const { success, authIdentity, error } = await authModuleService21      .authenticate(22        "emailpass",23       {24          url: req.url,25          headers: req.headers,26          query: req.query,27          body: req.body,28          authScope: "admin", // or custom actor type29          protocol: req.protocol,30        } as AuthenticationInput31      )32
33    if (!success) {34      // incorrect authentication details35      throw new MedusaError(36        MedusaError.Types.UNAUTHORIZED,37        error || "Incorrect authentication details"38      )39    }40
41    return new StepResponse({ authIdentity }, authIdentity?.id)42  },43  async (authIdentityId, { container }) => {44    if (!authIdentityId) {45      return46    }47    48    const authModuleService = container.resolve(Modules.AUTH)49
50    await authModuleService.deleteAuthIdentities([authIdentityId])51  }52)53
54export const authenticateUserWorkflow = createWorkflow(55  "authenticate-user",56  (input: Input) => {57    const { authIdentity } = authenticateUserStep(input)58
59    return new WorkflowResponse({60      authIdentity,61    })62  }63)

You can then execute the workflow in your custom API routes, scheduled jobs, or subscribers:

API Route
5import { authenticateUserWorkflow } from "../../workflows/authenticate-user"6
7export async function GET(8  req: MedusaRequest,9  res: MedusaResponse10) {11  const { result } = await authenticateUserWorkflow(req.scope)12    .run({13      req,14    })15
16  res.send(result)17}

Learn more about workflows in this documentation.


Configure Auth Module#

The Auth Module accepts options for further configurations. Refer to this documentation for details on the module's options.


Providers#

Medusa provides the following authentication providers out-of-the-box. You can use them to authenticate admin users, customers, or custom actor types.

Emailpass Provider
Google Provider
GitHub Provider

Server Guides#

Learn how to use the Auth Module in your customizations on the Medusa application server.

Create an Actor Type
Handle Password Reset Event
Create Auth Provider Module

Storefront Guides#

Learn how to integrate the Auth Module's features into your storefront.

Log-out Customer in Storefront
Login Customer in Storefront
Register Customer in Storefront
Reset Customer Password in Storefront
Retrieve Logged-In Customer in Storefront
Third-Party or Social Login in Storefront

References#

Find references for tools and resources related to the Auth Module, such as data models, methods, and more. These are useful for your customizations.

Workflows
JS SDK
Events Reference
Admin Widget Zones
Main Service Reference
Data Models Reference
Was this page helpful?
Edit this page
Ask Anything
FAQ
What is Medusa?
How can I create a module?
How can I create a data model?
How do I create a workflow?
How can I extend a data model in the Product Module?
Recipes
How do I build a marketplace with Medusa?
How do I build digital products with Medusa?
How do I build subscription-based purchases with Medusa?
What other recipes are available in the Medusa documentation?
Chat is cleared on refresh
Line break