How to Reset Passwords using Password Profiles

The One-Time Password Token request APIs can be used to perform a Password Reset scenario in your experience.

If you want to follow along, you need the following:

• A Commerce account and the Client ID and Client Secret of your store, available from your Commerce Manager.
• A front-end application or a custom application accessible to you in a web browser which accesses the Commerce API with the implicit token.
• An access token.

The following steps are used to set up the feature to be used.

1. Get the Account Authentication Settings
2. Create/Update the Password Profile
3. Create a User for testing
4. Create a Webhook

The following steps are used to perform a Password Reset

1. Create One-Time Password Token Request
2. Webhook used to send code to user
3. Exchange code for Account Management Authentication Token

Use the Account Authentication Settings API to obtain the authentication_realm. Additionally, update the setting for account_member_self_management to update_only if not set already. This will allow the user to reset their password using the Account Management Authentication Token.

Use the Password Profiles API to either create a new Password Profile, or update the existing Password Profile used for authentication. To enable the feature, set enable_one_time_password_token to true. Make note of the id for the next step.

First create a User Authentication Info to represent a user, then associate them to the Password Profile from the previous step using the User Authentication Password Profile Info API making note of the username.

Using the Integrations API, create an integration which observes the one-time-password-token-request.created event. This Integration should be used to send information from the event to the user. Most commonly this will be used to send an email template to the user, which would direct them to your page which handles password reset. For example, set integration_type to webhook and configuration.url to a url which can handle sending the email to the user like https://yourwebsite.com/one-time-password-token-notification which can handle the event and send an email.

Alternatively, you can set up Sendgrid or Postmark within Integrations Hub with an event mapping for one-time-password-token-request.created and configure your email template within the third-party system.

Example payload for one-time-password-token-request.created:

{
  "id": "31ca9869-a6eb-4f06-989c-17900fa12f2d",
  "store_id": "877baaf1-50b7-4cae-afa5-2431fa7b5ee4",
  "triggered_by": "one-time-password-token-request.created",
  "integration": {
    "id": "145d7084-7b00-4f10-9d55-0ecd49c1a2bb",
    "integration_type": "webhook",
    "name": "One Time Password notification",
    "description": "Send one time password notification"
  },
  "payload": {
    "authentication_realm_id": "063623f1-9182-4c8f-bb17-91d326e06e69",
    "created_at": "2023-09-05T14:53:01.584+00:00",
    "one_time_password_token": "lprvj4",
    "password_profile_id": "9a44bb7e-e377-4382-b36e-c8030aad1c2d",
    "purpose": "reset_password",
    "updated_at": "2023-09-05T14:53:01.584+00:00",
    "user_authentication_info": {
      "email": "john.doe@banks.com",
      "id": "459a2d49-ff3f-4589-b9fb-7e86ac7273f4",
      "name": "John Doe"
    },
    "user_authentication_password_profile_info": {
      "id": "d63be373-580d-4e16-818b-15513341e9b6",
      "password_profile_id": "9a44bb7e-e377-4382-b36e-c8030aad1c2d",
      "username": "john.doe@banks.com"
    }
  },
  "configuration": {
    "url": "https://webhook.site/24b00ff8-90ae-439f-a400-30c53d5ba964",
    "secret_key": ""
  }
}

Now that we have everything set up, the next steps will be to perform a Password Reset scenario.

Using the username and password profile ID above, initiate a Password Reset by creating a One Time Password Token Request with the purpose as reset_password. This API will send an event with the code and additional information to the Webhook we set up earlier. This is the API call that should be used upon initiating a Password Reset from your application.

From the above we can use the information provided in the event to direct the user to a Password Reset page. It is recommended to embed the following into your redirect or email template:

• password_profile_id
• username
• one_time_password_token

Additionally, you can also provide the following which will make resetting the user's password slightly easier in the next step:

• user_authentication_password_profile_info.id
• authentication_realm_id

An example redirect would be a page in your application such as https://yourwebsite.com/change_password?username=john.doe@banks.com&token=lprvj4

In your application, use the One Time Password Token from the previous step to generate an Account Management Authentication Token using Account Member Authentication. The Account Management Authentication Token can be used to update the password using Update User Authentication Password Profile Info.