Auth Identity and Actor Types

In this guide, you’ll learn about concepts related to identity and actors in the Auth Module.

What is an Auth Identity?#

The AuthIdentity data model represents a user registered by an authentication provider. When a user is registered using an authentication provider, the provider creates a record of AuthIdentity.

Then, when the user logs in with the same authentication provider, the associated auth identity is used to validate their credentials.

Actor Types#

An actor type is a type of user that can be authenticated. The Auth Module doesn't store or manage any user-like models, such as for customers or users. Instead, the user types are created and managed by other modules. For example, a customer is managed by the Customer Module.

When an auth identity is created for an actor type, the ID of the user is stored in the app_metadata property of the auth identity.

For example, an auth identity of a customer has the following app_metadata property:

Code
1{2  "app_metadata": {3    "customer_id": "cus_123"4  }5}

The ID of the user is stored in the key {actor_type}_id of the app_metadata property.

Protect Routes by Actor Type#

When you protect routes with the authenticate middleware, you specify in its first parameter the actor type that must be authenticated to access the API routes.

For example:

src/api/middlewares.ts
1import { 2  defineMiddlewares,3  authenticate,4} from "@medusajs/framework/http"5
6export default defineMiddlewares({7  routes: [8    {9      matcher: "/custom/admin*",10      middlewares: [11        authenticate("user", ["session", "bearer", "api-key"]),12      ],13    },14  ],15})

By specifying user as the first parameter of authenticate, only authenticated users of actor type user (admin users) can access API routes starting with /custom/admin.

Custom Actor Types#

You can define custom actor types that allow a custom user, managed by your custom module, to authenticate into Medusa.

For example, if you have a custom module with a Manager data model, you can authenticate managers with the manager actor type.

Learn how to create a custom actor type in the Create Manager Actor Type guide.