Users Architecture Overview
In this document, you’ll learn about the users architecture and invites in Medusa.
A user is an admin that can view and process sensitive and private information in the commerce store. A store in Medusa can have more than one user. Users can create or invite other users to manage the store.
A user is typically referred to as “admin” throughout the documentation and user guide.
User Entity Overview
Some of the
User entity attributes include:
password_hash: a string indicating the encrypted password of the user. Passwords are encrypted using the scrypt-kdf NPM package. The password hash is nullable, which can be useful if you want to integrate a third-party authentication service that does not require a password.
first_name: a string indicating the user’s first name.
last_name: a string indicating the user’s last name.
api_token: a string that holds the user’s API token. The API token can be used to send authenticated requests to admin endpoints, instead of using cookie session authentication. Check out the API reference to learn how to use it.
role: a string that indicates the role of the user. Its value can be either
role attribute does not actually provide permission or Access Control List (ACL) features within Medusa.
A user can create other users where they specify the user’s details and credentials, and the new user can immediately authenticate using their credentials.
Alternatively, a user can invite another user to join by just supplying the new user’s email. Then, the new user can accept the invite and provide their credentials.
Invite Entity Overview
An invitation is represented by the
Invite entity. Some of its attributes include:
user_email: a string indicating the email of the user.
role: a string indicating the role of the user. Similar to the
roleattribute, its value can be either
accepted: a boolean value indicating whether the invite has been accepted.
token: a string that is automatically generated when the invite is created. It’s a hash that is used to later accept the invitation.
expires_at: a date indicating when the invitation expires.
Invite Process Overview
You have full freedom in how you choose to implement the invite flow. This section explains how it’s implemented within the Medusa backend.
The invitation process typically follows these steps in the Medusa backend:
- A user creates an invite either using the Create Invite endpoint or the
createmethod. Part of creating an invite includes generating the token and setting the expiry date. By default, the expiry date is set to a week after the date of invitation creation.
- The new user receives the invite, typically through their email (although this is not implemented by default within the Medusa backend). The new user has to provide their details and password. The invite can be accepted either using the Accept Invite endpoint or using the
- When the new user accepts the invite, the invitation is validated first to ensure it’s not expired. If it’s not expired, a new user is created using the
UserService's create method.
If an invitation is expired, an existing user can resend the invite either using the Resend Invite endpoint or using the
InviteService's resend method. This would generate a new token and reset the expiry date.