Medusa Permissions Overview

medusa-permissions is an extensible Role-Based Access Control (RBAC) plugin for Medusa that extends traditional RBAC with context-aware parameter scoping (ABAC-like behavior), audit logging, and a comprehensive admin interface.\

#Core Concepts

#Actors

Actors are entities that perform actions in your system. Built-in actors include:

• User: Admin users in your Medusa system
• Customer: Your store's customers

You can also create custom actors for other entities like vendors, partners, or team members.

#Roles

Roles are collections of permissions. Users are assigned roles, which grant them specific capabilities:

• Hierarchy-aware (roles have priority levels)
• Composable (combine multiple roles)
• Managed through the admin interface

#Permissions

Permissions define what actions are allowed. Permission keys follow a hierarchical pattern:

• admin.orders.list
• admin.orders.update
• admin.permissions.roles.manage

The system supports wildcard matching:

• admin.orders.* - matches all order actions
• admin.* - matches all admin actions
• * - matches everything

#Context-Aware Parameters

Extend RBAC with runtime conditions. Built-in parameters include:

• Resource scoping: resource_id, store_id, sales_channel_id, region_id
• Actor scoping: actor_id, actor_type
• Field scoping: fields, route
• Role hierarchy: target_role, target_role_is_lower_priority

Example: Allow users to manage orders only in their assigned sales channel.

#Installation

npm install medusa-permissions
# or
yarn add medusa-permissions

#Basic Configuration

Add the plugin to your medusa-config.ts:

module.exports = {
  plugins: ["medusa-permissions"],
  modules: [
    {
      resolve: "medusa-permissions/modules/permissions",
      options: {
        permissions: [
          {
            resolve: "medusa-permissions/permissions/admin"
          }
        ],
        actors: [
          {
            resolve: "medusa-permissions/actors/user"
          },
          {
            resolve: "medusa-permissions/actors/customer"
          }
        ]
      }
    }
  ]
}

Then run migrations:

npx medusa db:migrate

#Enforcing Permissions

Add the provided middlewares to your src/api/middlewares.ts:

import { adminApiPermissionMiddlewares } from "medusa-permissions/middlewares/permissions";

export default defineMiddlewares({
  routes: [
    ...adminApiPermissionMiddlewares,
    // ... other middlewares ...
  ]
});

⚠️ Important: Configure the module and assign roles to admin users before adding middlewares, or you'll lock yourself out of the system.

#Rule Evaluation

The permission system uses a sophisticated evaluation order:

1. Rule Priority - Higher priority rules evaluated first
2. Specificity - More specific rules take precedence over general ones
3. Deny-First - Deny rules override allow rules as a security default

Wildcard fallback is supported: admin.orders.update -> admin.orders.* -> admin.* -> *

#Admin Interface

The plugin includes a dedicated admin interface accessible via:

• Extensions -> Permissions -> Roles (manage roles and permissions)
• Extensions -> Permissions -> Audit Logs (review authorization decisions)

#Audit Logging

Every permission evaluation is logged with:

• Actor and permission details
• Matched rule and role information
• Resolved context parameters
• Decision outcome and reasoning

Audit logs are enabled by default and can be disabled in module options:

{
  resolve: "medusa-permissions/modules/permissions",
  options: {
    enable_audit_logs: false,
    // ... other options ...
  }
}

#Built-in Extensions

• Admin Permissions: Pre-defined permissions for the Medusa Admin API
• Actor Providers: User and customer actor resolvers
• Middlewares: Pre-built enforcement middleware stack
• Admin UI: Full management interface