docs: updates following authentication flow changes (#8706)

* docs: updates following authentication flow changes * generate sidebar * added open api specs * fix up OAS * changes to existing pages * change sidebar items * update marketplace recipe
2024-08-27 15:47:39 +03:00
parent 9197bdd77b
commit 0c4f4c8a11
55 changed files with 1553 additions and 73 deletions
@@ -8,7 +8,27 @@ export const metadata = {

 # {metadata.title}

-In this document, you'll learn about how the Auth Provider is used in an authentication flow.
+In this document, you'll learn how to use the Auth Provider's main service's methods to implement an authentication flow.
+
+## How to Register an Auth Identity
+
+The `register` method of the Auth Module's main service creates an auth identity that can be authenticated later.
+
+For example:
+
+```ts
+const data = await authModuleService.register(
+  "emailpass",
+  // passed to auth provider
+  {
+    // ...
+  }
+)
+```
+
+This method calls the `register` method of the provider specified in the first parameter and returns its data.
+
+---

 ## How to Authenticate a User

@@ -26,9 +46,7 @@ const data = await authModuleService.authenticate(

 This method calls the `authenticate` method of the provider specified in the first parameter and returns its data.

---
-
-## Basic Authentication Flow
+### Basic Authentication Flow

 If the `authenticate` method returns the following object:

@@ -51,9 +69,7 @@ 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)

---
-
-## Authentication with Third-Party Service Flow
+### Authentication with Third-Party Service Flow

 If the `authenticate` method returns the following object:

@@ -68,7 +84,7 @@ It means the authentication process requires the user to perform an action with

 ![Diagram showcasing the first part of the third-party authentication flow](https://res.cloudinary.com/dza7lstvk/image/upload/v1711374847/Medusa%20Resources/third-party-auth-1_enyedy.jpg)

-### validateCallback
+#### validateCallback

 Providers handling this authentication flow must implement the `validateCallback` method. It implements the logic to validate the authentication with the third-party service.

@@ -95,4 +111,4 @@ data = {
 }
 ```

-![Diagram showcasing the second part of the third-party authentication flow](https://res.cloudinary.com/dza7lstvk/image/upload/v1711375123/Medusa%20Resources/third-party-auth-2_kmjxju.jpg)
+![Diagram showcasing the second part of the third-party authentication flow](https://res.cloudinary.com/dza7lstvk/image/upload/v1711375123/Medusa%20Resources/third-party-auth-2_kmjxju.jpg)
@@ -4,34 +4,79 @@ export const metadata = {

 # {metadata.title}

-In this document, you'll learn about the `/auth` route and how to use it to create or log-in users.
+In this document, you'll learn about the authentication routes and how to use them to create or log-in users.

-## `/auth` Route
+## Register Route

-The Medusa application defines an API route at `/auth/{actor_type}/{provider}` used to obtain a token used later for authentication purposes.
+The Medusa application defines an API route at `/auth/{actor_type}/{provider}/register` that creates an auth identity for an actor type, such as a `customer`. It returns a JWT token that you pass to an API route that creates the user.
+
+For example, if you're registering a customer, you:
+
+1. Send a request to `/auth/customer/emailpass/register` to retrieve the registration JWT token.
+2. Send a request to the [Create Customer API route](!api!/store#customers_postcustomers) to create the customer, passing the [JWT token in the header](!api!/store#authentication).
+
+### Path Parameters

 Its path parameters are:

 - `{actor_type}`: the actor type of the user you're authenticating. For example, `customer`.
 - `{provider}`: the auth provider to handle the authentication. For example, `emailpass`.

+### Request Body Parameters
+
 This route accepts in the request body the data that the specified authentication provider requires to handle authentication.

 For example, the EmailPass provider requires an `email` and `password` fields in the request body.

-If the authentication is successful, you'll receive a `token` field in the response body.
+### Response Fields

---
+If the authentication is successful, you'll receive a `token` field in the response body object:

-## How to Use the Authentication Token
-
-There are two ways the returned authentication token is useful:
-
-1. Send authenticated requests to restricted routes. For example, if the token is of an admin user, you use it in the bearer header of subsequent requests to the admin API routes.
-2. Before creating a user of an actor type, such as a `customer` or a custom actor type. You use it in the bearer header of the request to the API route that creates the user.
+```json
+{
+  "token": "..."
+}
+```

 <Note title="Example">

 [How to register Customers using the authentication route](../../../storefront-development/customers/register/page.mdx).

 </Note>
+
+---
+
+## Auth Route
+
+The Medusa application defines an API route at `/auth/{actor_type}/{provider}` that authenticates a user of an actor type. It returns a JWT token that can be passed in [the header of subsequent requests](!api!/store#authentication) to send authenticated requests.
+
+For example, if you're authenticating a customer, you send a request to `/auth/customer/emailpass`.
+
+### Path Parameters
+
+Its path parameters are:
+
+- `{actor_type}`: the actor type of the user you're authenticating. For example, `customer`.
+- `{provider}`: the auth provider to handle the authentication. For example, `emailpass`.
+
+### Request Body Parameters
+
+This route accepts in the request body the data that the specified authentication provider requires to handle authentication.
+
+For example, the EmailPass provider requires an `email` and `password` fields in the request body.
+
+### Response Fields
+
+If the authentication is successful, you'll receive a `token` field in the response body object:
+
+```json
+{
+  "token": "..."
+}
+```
+
+<Note title="Example">
+
+[How to login Customers using the authentication route](../../../storefront-development/customers/login/page.mdx).
+
+</Note>
@@ -248,7 +248,7 @@ This route is only accessible by authenticated managers. You access the manager

 To authenticate managers:

-1. Send a `POST` request to `/auth/manager/emailpass` to create an auth identity for the manager:
+1. Send a `POST` request to `/auth/manager/emailpass/register` to create an auth identity for the manager:

 ```bash
 curl -X POST 'http://localhost:9000/auth/manager/emailpass' \
@@ -499,10 +499,10 @@ To test out the above API route:
 npm run dev
 ```

-2. Retrieve a JWT token from the `/auth/vendor/emailpass` API route:
+2. Retrieve a JWT token from the `/auth/vendor/emailpass/register` API route:

-```bash apiTesting testApiUrl="http://localhost:9000/auth/vendor/emailpass" testApiMethod="POST" testBodyParams={{ "email": "admin@medusa-test.com", "password": "supersecret" }}
-curl -X POST 'http://localhost:9000/auth/vendor/emailpass' \
+```bash apiTesting testApiUrl="http://localhost:9000/auth/vendor/emailpass/register" testApiMethod="POST" testBodyParams={{ "email": "admin@medusa-test.com", "password": "supersecret" }}
+curl -X POST 'http://localhost:9000/auth/vendor/emailpass/register' \
 -H 'Content-Type: application/json' \
 --data-raw '{
    "email": "admin@medusa-test.com",
@@ -9,7 +9,7 @@ export const metadata = {
 To register a customer, you implement the following steps:

 1. Show the customer a form to enter their details.
-2. Send a `POST` request to the `/auth/customer/emailpass` API route to obtain a JWT token.
+2. Send a `POST` request to the `/auth/customer/emailpass/register` API route to obtain a JWT token.
 3. Send a request to the [Create Customer API route](!api!/store#customers_postcustomers) pass the JWT token in the header.

 For example:
@@ -28,7 +28,7 @@ export const fetchHighlights = [
  const handleRegistration = async () => {
    // obtain JWT token
    const { token } = await fetch(
-      `http://localhost:9000/auth/customer/emailpass`,
+      `http://localhost:9000/auth/customer/emailpass/register`,
      {
        credentials: "include",
        method: "POST",