docs: document registering user with existing email (#10859)

2025-01-07 12:39:16 +02:00
parent 632600ee11
commit f8c20e5ee4
5 changed files with 183 additions and 43 deletions
@@ -53,7 +53,7 @@ This method calls the `authenticate` method of the provider specified in the fir
 The basic authentication flow requires first using the `register` method, then the `authenticate` method:

 ```ts
-const { success, authIdentity } = await authModuleService.register(
+const { success, authIdentity, error } = await authModuleService.register(
  "emailpass",
  // passed to auth provider
  {
@@ -61,6 +61,12 @@ const { success, authIdentity } = await authModuleService.register(
  }
 )

+if (error) {
+  // registration failed
+  // TODO return an error
+  return
+}
+
 // later (can be another route for log-in)
 const { success, authIdentity, location } = await authModuleService.authenticate(
  "emailpass",
@@ -87,6 +93,15 @@ Check out the [AuthIdentity](/references/auth/models/AuthIdentity) reference for

 ![Diagram showcasing the basic authentication flow](https://res.cloudinary.com/dza7lstvk/image/upload/v1711373749/Medusa%20Resources/basic-auth_lgpqsj.jpg)

+### Auth Identity with Same Identifier
+
+If an auth identity, such as a `customer`, tries to register with an email of another auth identity, the `register` method returns an error. This can happen either if another customer is using the same email, or an admin user has the same email.
+
+There are two ways to handle this:
+
+- Consider the customer authenticated if the `authenticate` method validates that the email and password are correct. This allows admin users, for example, to authenticate as customers.
+- Return an error message to the customer, informing them that the email is already in use.
+
 ---

 ## Auth Flow 2: Third-Party Service Authentication
@@ -8,9 +8,7 @@ In this document, you’ll learn about concepts related to identity and actors i

 ## What is an Auth Identity?

-The [AuthIdentity data model](/references/auth/models/AuthIdentity) represents a user registered by an [authentication provider](../auth-providers/page.mdx).
-
-When a user is registered using an authentication provider, it creates a record of `AuthIdentity`.
+The [AuthIdentity data model](/references/auth/models/AuthIdentity) represents a user registered by an [authentication provider](../auth-providers/page.mdx). When a user is registered using an authentication provider, the provider creates a record of `AuthIdentity`.

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

@@ -18,11 +16,7 @@ Then, when the user logs-in in the future with the same authentication provider,

 ## 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.
+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](../../customer/page.mdx).

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

@@ -29,13 +29,19 @@ The steps are:
 ![Diagram showcasing the basic authentication flow between the frontend and the Medusa application](https://res.cloudinary.com/dza7lstvk/image/upload/v1725539370/Medusa%20Resources/basic-auth-routes_pgpjch.jpg)

 1. Register the user with the [Register Route](#register-route).
-5. Use the authentication token to create the user with their respective API route.
+2. Use the authentication token to create the user with their respective API route.
    - For example, for customers you would use the [Create Customer API route](!api!/store#customers_postcustomers).
    - For admin users, you accept an invite using the [Accept Invite API route](!api!/admin#invites_postinvitesaccept)
-2. Authenticate the user with the [Auth Route](#auth-route).
+3. Authenticate the user with the [Auth Route](#auth-route).

 After registration, you only use the [Auth Route](#auth-route) for subsequent authentication.

+<Note>
+
+To handle errors related to existing identities, refer to [this section](#handling-existing-identities).
+
+</Note>
+
 ### 2. Third-Party Service Authenticate Flow

 This authentication flow authenticates the user with a third-party service, such as Google.
@@ -115,6 +121,35 @@ If the authentication is successful, you'll receive a `token` field in the respo

 Use that token in the header of subsequent requests to send authenticated requests.

+### Handling Existing Identities
+
+An auth identity with the same email may already exist in Medusa. This can happen if:
+
+- Another actor type is using that email. For example, an admin user is trying to register as a customer.
+- The same email belongs to a record of the same actor type. For example, another customer has the same email.
+
+In these scenarios, the Register Route will return an error instead of a token:
+
+```json
+{
+  "type": "unauthorized",
+  "message": "Identity with email already exists"
+}
+```
+
+To handle these scenarios, you can use the [Login Route](#login-route) to validate that the email and password match the existing identity. If so, you can allow the admin user, for example, to register as a customer.
+
+Otherwise, if the email and password don't match the existing identity, such as when the email belongs to another customer, the [Login Route](#login-route) returns an error:
+
+```json
+{
+  "type": "unauthorized",
+  "message": "Invalid email or password"
+}
+```
+
+You can show that error message to the customer.
+
 ---

 ## Login Route