Menu

Auth API Routes

Auth API routes allow you to manage a customer's authentication.

GET /auth/customer/providers#

List Auth Providers for Customers

Retrieve a list of auth providers for the customer actor type. This is useful to show the authentication option for the available providers.

Authentication: none.

Request examples

Responses

200 OK

providersobject[]
The list of auth providers.

400, 401, 404, 409, 422, 500: an error response is returned.

POST /auth/customer/{auth_provider}#

Authenticate Customer

Authenticate a customer and receive the JWT token to be used in the header of subsequent requests.

When used with a third-party provider, such as Google, the request returns a location property. You redirect to the specified URL in your storefront to continue authentication with the third-party service.

Authentication: none.

Path parameters

auth_providerstring
The provider used for authentication.
Example: emailpass

Request body (application/json)

The request body is an empty JSON object.

Request examples

Responses

200 OK

tokenstringOptional
The JWT token used for registration or authentication.
locationstringOptional
The location to redirect the user to for further authentication with the third-party provider.

400, 401, 404, 409, 422, 500: an error response is returned.

POST /auth/customer/{auth_provider}/callback#

Validate Authentication Callback

This API route is used by your storefront or frontend application when a third-party provider redirects to it after authentication. It validates the authentication with the third-party provider and, if successful, returns an authentication token. All query parameters received from the third-party provider, such as code, state, and error, must be passed as query parameters to this route. You can decode the JWT token using libraries like react-jwt in the storefront. If the decoded data doesn't have an actor_id property, then you must register the customer using the Create Customer API route passing the token in the request's Authorization header.

Authentication: none.

Path parameters

auth_providerstring
The provider used for authentication.
Example: google

Request examples

Responses

200 OK

tokenstring
The JWT token used for registration or authentication.

400, 401, 404, 409, 422, 500: an error response is returned.

POST /auth/customer/{auth_provider}/register#

Retrieve Registration JWT Token

This API route retrieves a registration JWT token of a customer that hasn't been registered yet. The token is used in the header of requests that create a customer.

Authentication: none.

Path parameters

auth_providerstring
The provider used for authentication.
Example: emailpass

Request body (application/json)

The request body is an empty JSON object.

Request examples

Responses

200 OK

tokenstring
The JWT token used for registration or authentication.

400, 401, 404, 409, 422, 500: an error response is returned.

POST /auth/customer/{auth_provider}/reset-password#

Generate Reset Password Token for Customer

Generate a reset password token for a customer. This API route doesn't reset the customer password or send them the reset instructions in a notification.

Instead, This API route emits the auth.password_reset event, passing it the token as a payload. You can listen to that event in a subscriber as explained in this guide, then send the customer a notification. The notification is sent using a Notification Module Provider, and it should have a URL that accepts a token query parameter, allowing the customer to reset their password from the storefront.

Use the generated token to update the customer's password using the Reset Password API route.

Authentication: none.

Path parameters

auth_providerstring
The provider used for authentication.
Example: emailpass

Request body (application/json)

identifierstring
The customer's identifier for the selected auth provider. For example, for the emailpass auth provider, the value is the customer's email.
Example: customer@gmail.com
metadataobjectOptional
Optional metadata to include with the reset password token generation request.

Request examples

Responses

201 OK. The response body has the content type text/plain.

400, 401, 404, 409, 422, 500: an error response is returned.

Emitted events

  • auth.password_reset: Emitted when a reset password token is generated. You can listen to this event to send a reset password email to the user or customer, for example.

POST /auth/customer/{auth_provider}/update#

Reset a Customer's Password

Reset a customer's password using a reset-password token generated with the Generate Reset Password Token API route. You pass the token as a bearer token in the request's Authorization header.

Authentication: reset password token.

Path parameters

auth_providerstring
The provider used for authentication.
Example: emailpass

Request body (application/json)

The request body is an empty JSON object.

Request examples

Responses

200 OK

successboolean
Whether the password was reset successfully.

400, 401, 404, 409, 422, 500: an error response is returned.

POST /auth/session#

Set Authentication Session

Set the cookie session ID of a customer. The customer must be previously authenticated with the /auth/customer/{provider} API route first, as the JWT token is required in the header of the request.

Authentication: none.

Request examples

Responses

200 OK

userobject
The customer's details.

400, 401, 404, 409, 422, 500: an error response is returned.

DELETE /auth/session#

Delete Authentication Session

Deletes the cookie session ID previously set for authentication.

Authentication: none.

Request examples

Responses

200 OK

successboolean
Whether the session was deleted successfully.

400, 401, 404, 409, 422, 500: an error response is returned.

POST /auth/token/refresh#

Refresh Authentication Token

Refresh the authentication token of a customer. This is useful after authenticating a customer with a third-party service to ensure the token holds the new user's details, or when you don't want customers to re-login every day.

Authentication: none.

Request examples

Responses

200 OK

tokenstring
The JWT token used for registration or authentication.

400, 401, 404, 409, 422, 500: an error response is returned.

POST /auth/verification/confirm#

Confirm Customer Verification

Confirm a verification token of the customer. This API route is used as the last step part of the email verification flow. It can also be used for custom flows, such as phone number verification. Once successfully verified, a customer can complete their registration and log into their account.

Authentication: none.

Request body (application/json)

codestring
The token, OTP, or any other code that was sent to the customer for verification.
code_providerstringOptional
The provider to use for verification. This is optional. When not provided, the default token provider is used.

Request examples

Responses

200 OK

400, 401, 404, 409, 422, 500: an error response is returned.

POST /auth/verification/request#

Request Customer Verification

Create a verification request for a customer. This API route is used when a customer logs in, but their email requires verification. It can also be used for custom flows, such as phone number verification. Once successfully requested, a verification code will be generated and an auth.verification_requested event will be emitted. You can listen to this event and decide how to deliver the code to the customer.

Authentication: none.

Request body (application/json)

entity_idstring
The identifier of the user or customer. For example, an email address.
entity_typestring
The type of identity being verified. For example, "email" or "phone_number".
code_providerstring
The provider to use to create the verification token or code. By default, Medusa provides a token provider that generates a random token. You can also implement your own provider to generate a code or OTP.
metadataobjectOptional
Custom key-value pairs that can be passed to the verification request. This is optional and can be used to store additional information related to the verification request.

Request examples

Responses

201 OK

400, 401, 404, 409, 422, 500: an error response is returned.

Emitted events

  • auth.verification_requested: Emitted when a verification code is generated. You can listen to this event and decide how to deliver the code to the user or customer. The payload changed in v2.17.0: actor_type and provider_identity_id were removed, provider was renamed to code_provider, and entity_type was added. Subscribers written before v2.17.0 must be updated to use the payload below.
Found a problem with this page?Report Issue
Edited Nov 14·Edit this page