www/apps/resources/app/commerce-modules/auth/authentication-route/page.mdx
export const metadata = {
title: How to Use Authentication Routes,
}
In this document, you'll learn about the authentication routes and how to use them to create and log-in users, and reset their password.
<Note>These routes are added by Medusa's HTTP layer, not the Auth Module.
</Note>This authentication flow doesn't require validation with third-party services.
<Note title="Example">How to register customer in storefront using basic authentication flow.
</Note>The steps are:
After registration, you only use the Auth Route for subsequent authentication.
<Note>To handle errors related to existing identities, refer to this section.
</Note>This authentication flow authenticates the user with a third-party service, such as Google.
<Note title="Example">How to authenticate customer with a third-party provider in the storefront..
</Note>It requires the following steps:
location property in the response, must redirect to the returned location.code query parameter. So, make sure your third-party service is configured to redirect to your frontend page after successful authentication.code and state query parameters.actor_id property, then the user is already registered. So, use this token for subsequent authenticated requests.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.
curl -X POST http://localhost:9000/auth/{actor_type}/{providers}/register
-H 'Content-Type: application/json' \
--data-raw '{
"email": "[email protected]"
// ...
}'
This API route is useful for providers like emailpass that uses custom logic to authenticate a user. For authentication providers that authenticate with third-party services, such as Google, use the Auth Route instead.
For example, if you're registering a customer, you:
/auth/customer/emailpass/register to retrieve the registration JWT token.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.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 object:
{
"token": "..."
}
Use that token in the header of subsequent requests to send authenticated requests.
An auth identity with the same email may already exist in Medusa. This can happen if:
In these scenarios, the Register Route will return an error instead of a token:
{
"type": "unauthorized",
"message": "Identity with email already exists"
}
To handle these scenarios, you can use the 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 returns an error:
{
"type": "unauthorized",
"message": "Invalid email or password"
}
You can show that error message to the customer.
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 to send authenticated requests.
curl -X POST http://localhost:9000/auth/{actor_type}/{providers}
-H 'Content-Type: application/json' \
--data-raw '{
"email": "[email protected]"
// ...
}'
For example, if you're authenticating a customer, you send a request to /auth/customer/emailpass.
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.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.
For the GitHub and Google providers, you can pass a callback_url body parameter that overrides the callbackUrl set in the provider's configurations.
This is useful if you want to redirect the user to a different URL after authentication based on their actor type. For example, you can set different callback_url for admin users and customers.
If the authentication is successful, you'll receive a token field in the response body object:
{
"token": "..."
}
Use that token in the header of subsequent requests to send authenticated requests.
If the authentication requires more action with a third-party service, you'll receive a location property:
{
"location": "https://..."
}
Redirect to that URL in the frontend to continue the authentication process with the third-party service.
<Note title="Example">How to login Customers using the authentication route.
</Note>The Medusa application defines an API route at /auth/{actor_type}/{provider}/callback that's useful for validating the authentication callback or redirect from third-party services like Google.
curl -X POST http://localhost:9000/auth/{actor_type}/{providers}/callback?code=123&state=456
Refer to the third-party authentication flow section to see how this route fits into the authentication flow.
</Note>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, google.This route accepts all the query parameters that the third-party service sends to the frontend after the user completes the authentication process, such as the code and state query parameters.
If the authentication is successful, you'll receive a token field in the response body object:
{
"token": "..."
}
In your frontend, decode the token using tools like react-jwt:
actor_id property, the user is already registered. So, use this token for subsequent authenticated requests.The decoded data may look like this:
{
"actor_id": "", // Empty if the user is not registered
"user_metadata": {
"email": "[email protected]"
}
// other fields...
}
The Medusa application defines an API route at /auth/token/refresh that's useful after authenticating a user with a third-party service to populate the user's token with their new information.
It requires the user's JWT token that they received from the authentication or callback routes.
curl -X POST http://localhost:9000/auth/token/refresh \
-H 'Authorization: Bearer {token}'
If the token was refreshed successfully, you'll receive a token field in the response body object:
{
"token": "..."
}
Use that token in the header of subsequent requests to send authenticated requests.
To reset a user's password:
auth.password_reset event, passing the token in the payload.Storefront Development: How to Reset a Customer's Password.
</Note>The Medusa application defines an API route at /auth/{actor_type}/{auth_provider}/reset-password that emits the auth.password_reset event, passing the token in the payload.
curl -X POST http://localhost:9000/auth/{actor_type}/{providers}/reset-password
-H 'Content-Type: application/json' \
--data-raw '{
"identifier": "[email protected]"
}'
This API route is useful for providers like emailpass that store a user's password and use it for authentication.
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.This route accepts in the request body an object having the following property:
identifier: The user's identifier in the specified auth provider. For example, for the emailpass auth provider, you pass the user's email.If the authentication is successful, the request returns a 201 response code.
The Medusa application defines an API route at /auth/{actor_type}/{auth_provider}/update that accepts a token and, if valid, updates the user's password.
curl -X POST http://localhost:9000/auth/{actor_type}/{providers}/update
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer {token}' \
--data-raw '{
"email": "[email protected]",
"password": "supersecret"
}'
This API route is useful for providers like emailpass that store a user's password and use it for logging them in.
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.Before Medusa v2.6, you passed the token as a query parameter. Now, you must pass it in the Authorization header.
In the request's authorization header, you must pass the token generated using the Generate Reset Password Token route. You pass it as a bearer token.
This route accepts in the request body an object that has the data necessary for the provider to update the user's password.
For the emailpass provider, you must pass the following properties:
email: The user's email.password: The new password.If the authentication is successful, the request returns an object with a success property set to true:
{
"success": "true"
}