Help

Manage Roles in Medusa Admin

EnterpriseBeta

In this guide, you'll learn how to manage roles in the Medusa Admin.

Enterprise feature: Roles are part of the role-based access control (RBAC) feature, which is an enterprise feature. A developer must enable it in your Medusa configuration before the Roles and Policies settings appear. If you don't find these settings, reach out to your development team.

What is a Role?#

A role groups a set of permissions, called policies, under a name such as "Product Manager". You assign roles to admin users to control what they can access and do in the Medusa Admin.

When You Don't Have Access#

Your roles decide which parts of the Medusa Admin you can open. When you try to open a page that your roles don't cover, the dashboard shows an Access Denied message instead of the page, along with the permission the page requires. Nothing is broken, and you can keep using the pages you do have access to.

If your account has no permissions at all, the dashboard sends you to a No permissions yet page after you log in, instead of a section of the store. Reach out to your administrator to request access to the areas you need.

When you have at least one permission, the dashboard opens the first section you can access after you log in, such as Orders or Products.

View Roles#

Requires policy:rbac_role:read

To view the roles in your store, go to Settings → Roles. In the list, you can see each role's name and description. You can also search and sort the roles to find a specific one.

To view a role's details, click on it in the list. The role's details page shows its general information, the users assigned to it, and the permissions it grants. To see the assigned policies, you also need the rbac_policy:read policy. To see the assigned users, you also need the user:read and rbac_role_assignment:read policies.

Create a Role#

Requires policies (all of):rbac_role:createrbac_policy:read

To create a role:

Go to Settings → Roles.
Click the Create button in the top-right corner.
In the Details tab, enter a name and an optional description for the role.
Click Continue to move to the Permissions tab.
Select the permissions that this role should grant. Each permission allows an operation, such as read or create, on a resource, such as products or orders.
- To learn which policies common roles need, refer to the Common Roles guide.
Click Create.

The role now appears in the list, and you can assign it to users.

Note: The Permissions tab only lists the policies that you hold yourself. So, you can't create a role that grants more access than you have.

Edit a Role's Details#

Requires policy:rbac_role:update

To edit a role's name or description:

Go to the role's details page.
Click the icon at the top-right of the first section.
Choose Edit from the dropdown.
In the side window that opens, edit the role's name or description.
Click Save.

Manage a Role's Permissions#

Requires policies (all of):rbac_role:updaterbac_policy:read

To change the permissions that a role grants:

Go to the role's details page.
Click the icon at the top-right of the first section.
Choose Manage permissions from the dropdown.
In the form that opens, select or unselect the permissions for this role. You can use the search to find specific permissions.
Click Save.

Users assigned this role gain or lose access based on the permissions you change.

Note: The form only lists the policies that you hold yourself, so you can't add or remove policies that you don't have. When you save, the role keeps any policies it has that you don't hold.

Assign Users to a Role#

Requires policies (all of):user:updaterbac_role_assignment:createuser:readrbac_role_assignment:read

To assign users to a role:

Go to the role's details page.
In the Users section, click the Add button.
Select the users you want to assign this role to. You can't select users who already have the role.
Click Save.

Note: You can only assign a role if you have all the permissions that the role grants. If you don't, the Add button doesn't appear in the Users section.

Remove Users from a Role#

Requires policies (all of):user:updaterbac_role_assignment:deleteuser:readrbac_role_assignment:read

To remove a user from a role, find the user in the Users section, click the icon at the end of their row, and choose Remove. Then, click Continue in the confirmation pop-up.

To remove multiple users at once, select the users in the Users section, then click the Remove button in the command bar at the bottom of the page. Click Continue to confirm.

Note: As with assigning users, you can only remove users from a role if you have all the permissions that the role grants.You also can't remove the last user that has the Super Admin role. Assign the Super Admin role to another user first.

View a User's Roles#

Requires policies (all of):user:readrbac_role:readrbac_role_assignment:read

You can also see the roles of a specific user:

Go to Settings → Users.
Click on the user in the list.
Scroll to the Roles section, which lists every role assigned to that user.

Click on a role in the list to go to its details page, where you can change its permissions or the users assigned to it.

Delete a Role#

Requires policy:rbac_role:delete

Warning: Deleting a role is irreversible. Users assigned to the role lose the access it granted.

Note: You can't delete the built-in Super Admin role.

To delete a role:

Go to the role's details page.
Click the icon at the top-right of the first section.
Choose Delete from the dropdown.
Confirm deleting the role in the pop-up.

You can also delete a role from the Settings → Roles list. Click the icon at the end of the role's row and choose Delete.

Was this guide helpful?