---
title: Reset forgotten passwords
description: The AM UI includes pages for users to reset their forgotten passwords. You can, however, create a RESTful application to leverage the user self-service features.
component: pingam
version: 8.1
page_id: pingam:user-self-service:uss-forgotten-password
canonical_url: https://docs.pingidentity.com/pingam/8.1/user-self-service/uss-forgotten-password.html
keywords: ["Self-Service", "Password Reset"]
page_aliases: ["user-self-service-guide:uss-forgotten-password.adoc"]
---

# Reset forgotten passwords

The AM UI includes pages for users to reset their forgotten passwords. You can, however, create a RESTful application to leverage the user self-service features.

Forgotten password flow in the UI

![The forgotten password feature supports multiple user flows, depending on how it is configured.](_images/forgotten-password-flow.png)

When performing user self-service functions, you can enable one or more security methods such as email validation, Google reCAPTCHA, knowledge-based authentication, or custom plugins.

Each configured security method requires particular security data that AM requests from the client for verification.

A unique token is provided in the second response to the client that must be used in any subsequent requests, so that AM can maintain the state of the user self-service process.

1. Send a GET request to the `/selfservice/forgottenPassword` endpoint.

   Notice that the request does not require any form of authentication:

   ```bash
   $ curl \
   --header "Accept-API-Version: resource=1.0" \
   "https://am.example.com:8443/am/json/realms/root/selfservice/forgottenPassword"
   {
     "type": "captcha",
     "tag": "initial",
     "requirements": {
       "$schema": "http://json-schema.org/draft-04/schema#",
       "description": "Captcha stage",
       "type": "object",
       "required": [
         "response"
       ],
       "properties": {
         "response": {
           "recaptchaSiteKey": "6Lfr1…​cIqbd",
           "description": "Captcha response",
           "type": "string"
         }
       }
     }
   }
   ```

   In this example, the Google reCAPTCHA plugin is enabled, so the first required item of security data is of the `captcha` type.

2. Send a POST request to the `/selfservice/forgottenPassword` endpoint with a query string containing `_action=submitRequirements`. In the POST data, include an `input` element in the JSON structure, which should contain values for each element in the `required` array of the response.

   In this example, the `response` value required is the user input provided after completing the Google reCAPTCHA challenge:

   ```bash
   $ curl \
   --header "Accept-API-Version: resource=1.0" \
   --request POST \
   --header "Content-Type: application/json" \
   --data \
   '{
       "input": {
           "response": "03AHJ…​qiE1x4"
       }
   }' \
   "https://am.example.com:8443/am/json/realms/root/selfservice/forgottenPassword?_action=submitRequirements"
   {
       "type": "userQuery",
       "tag": "initial",
       "requirements": {
           "$schema": "http://json-schema.org/draft-04/schema#",
           "description": "Find your account",
           "type": "object",
           "required": [
               "queryFilter"
           ],
           "properties": {
               "queryFilter": {
                   "description": "filter string to find account",
                   "type": "string"
               }
           }
       },
       "token": "eyAicHis…​PIF-lN4s"
   }
   ```

   If the input value was accepted, AM continues with the password reset process and specifies the information required next. In this example, the Google reCAPTCHA was verified and AM is requesting details about the account for the password reset, which must be provided in a `queryFilter` element.

   The value of the `token` element should be included in this and all subsequent requests to AM for this reset process.

3. Send a POST request to AM with a `queryFilter` value in the POST data containing the username of the subject with the password to replace.

   For more information on query filters, see [Query](../am-rest/rest-intro.html#about-crest-query).

   ```bash
   $ curl \
   --request POST \
   --header "Content-Type: application/json" \
   --data \
   '{
       "input": {
           "queryFilter": "uid eq \"bjensen\""
       },
       "token": "eyAicHis…​PIF-lN4s"
   }' \
   "https://am.example.com:8443/am/json/realms/root/selfservice/forgottenPassword?_action=submitRequirements"
   {
       "type": "kbaSecurityAnswerVerificationStage",
       "tag": "initial",
       "requirements": {
           "$schema": "http://json-schema.org/draft-04/schema#",
           "description": "Answer security questions",
           "type": "object",
           "required": [
               "answer1"
           ],
           "properties": {
               "answer1": {
                   "systemQuestion": {
                       "en": "What was the model of your first car?"
                   },
                   "type": "string"
               }
           }
       },
       "token": "eyAicHis…​PIF-lN4s"
   }
   ```

   If a single subject is located that matches the provided query filter, the password reset process continues.

   If a subject is not found, an HTTP 400 Bad Request status is returned, along with an error message in the JSON data:

   ```json
   {
       "code": 400,
       "reason": "Bad Request",
       "message": "Unable to find account"
   }
   ```

4. Continue sending POST data to AM containing the requested information, in the format specified in the response.

   Also return the `token` value in the POST data, so that AM can track the stages of the password reset process.

   ```bash
   $ curl \
   --request POST \
   --header "Content-Type: application/json" \
   --data \
   '{
       "input": {
           "answer1": "Mustang"
       },
       "token": "eyAicHis…​PIF-lN4s"
   }' \
   "https://am.example.com:8443/am/json/realms/root/selfservice/forgottenPassword?_action=submitRequirements"
   {
       "type": "resetStage",
       "tag": "initial",
       "requirements": {
           "$schema": "http://json-schema.org/draft-04/schema#",
           "description": "Reset password",
           "type": "object",
           "required": [
               "password"
           ],
           "properties": {
               "password": {
                   "description": "Password",
                   "type": "string"
               }
           }
           "code": "cf88bb63-b59c-4792-8fdf-2bcc00b0ab06"
       },
       "token": "eyAicHis…​PIF-lN4s"
   }
   ```

5. When AM has received all the requested information, it sets `type` to `resetStage` and returns a unique `code` value in the response. You can now specify a new password in the POST data, along with both the `code` and `token` values:

   ```bash
   $ curl \
   --request POST \
   --header "Content-Type: application/json" \
   --data \
   '{
       "input": {
           "password": "5tr0ng~P4s5worD!"
       },
       "code": "cf88bb63-b59c-4792-8fdf-2bcc00b0ab06",
       "token": "eyAicHis…​PIF-lN4s"
   }' \
   "https://am.example.com:8443/am/json/realms/root/selfservice/forgottenPassword?_action=submitRequirements"
   {
       "type": "activityAuditStage",
       "tag": "end",
       "status": {
           "success": true
       },
       "additions": {}
   }
   ```

   When the process is complete, the `tag` element has a value of `end`. If the `success` element in `status` has a value of `true`, the password reset is complete and the new password is now active.

   If the password is not accepted, an HTTP 400 Bad Request status is returned along with an error message:

   ```json
   {
       "code": 400,
       "reason": "Bad Request",
       "message": "Minimum password length is 8."
   }
   ```