Menu

Auth API Routes

Auth API routes allow you to manage an admin user's authentication.

DELETE /auth/mfa/factors/{id}#

Disable a Multi-Factor Authentication (MFA) Factor

Disable a multi-factor authentication (MFA) factor for the authenticated user. Once disabled, the factor can no longer be used to verify MFA challenges. When disabling a recovery-code factor, a valid recovery code must be provided in the request body.

Authentication: none.

Path parameters

idstring
The MFA factor's ID.

Request body (application/json)

methodstringOptional
The MFA method used to authorize disabling the factor (for example, recovery-code).
codestringOptional
The verification code associated with the provided method, used to confirm the disable action.

Request examples

Responses

200 OK

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

POST /auth/session#

Set Authentication Session

Set the cookie session ID of an admin user. The admin must be previously authenticated with the /auth/user/{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 user'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 user. This is useful after authenticating a user with a third-party service to ensure the token holds the new user's details, or when you don't want users 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.

GET /auth/user/providers#

List Auth Providers for Admin Users

Retrieve a list of auth providers for the user 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/user/{auth_provider}#

Authenticate User

Authenticate a user 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 frontend 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/user/{auth_provider}/callback#

Validate Authentication Callback

This API route is used by your dashboard 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 frontend. If the decoded data doesn't have an actor_id property, then you must create a user, typically using the Accept Invite 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/user/{auth_provider}/register#

Retrieve Registration JWT Token

This API route retrieves a registration JWT token of a user that hasn't been registered yet. The token is used in the header of requests that create a user, such as the Accept Invite API route.

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/user/{auth_provider}/reset-password#

Generate Reset Password Token for Admin User

Generate a reset password token for an admin user. This API route doesn't reset the admin's 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 user a notification. The notification is sent using a Notification Module Provider, and it should have the URL to reset the password in the Medusa Admin dashboard, such as http://localhost:9000/app/reset-password?token=123.

Use the generated token to update the user'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 identifier of the admin user. For example, their email address.
Example: admin@medusa-test.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/user/{auth_provider}/update#

Reset an Admin User's Password

Reset an admin user'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.

Found a problem with this page?Report Issue
Edited Nov 14·Edit this page