Reset a password for a user (user self-service)

This topic describes how to reset a password on behalf of a user both during and after authentication.

Reset a password during authentication

Using the CyberArk Identity authentication APIs, you can reset a password on behalf of a user during authentication. This is typically used when a user forgets their password and needs to reset it in order to authenticate.

Before continuing, ensure that you are familiar with:

To perform a password reset using the API:

Invoke /Security/StartAuthentication.
Check the JSON response to see if AllowForgotPassword is set to true. For example:
```
{
	"success": true,
	"Result": {
		"ClientHints": {
			"PersistDefault": false,
			"AllowForgotPassword": true,
			"AllowPersist": true
			},
		"TenantId": "AAA3226",
		...
	}
}
```
The value of the AllowForgotPassword field is based on whether the Forgot Password option is enabled in the user's policy. If the value is true, you can continue to the next step. If the value is false, the password cannot be reset for the user.
Provide a user interface element to the user, such as a Forgot Password button, which allows the user to trigger the password reset process.

When the user invokes this user interface element (for example, clicks a Forgot Password button), call the /Security/AdvanceAuthentication endpoint and set the Action field in the body of the request to ForgotPassword. For example:

POST /Security/AdvanceAuthentication

{
	"TenantId": "ABC1234",
	"SessionId": "1db90fe4-3b96-4c3e-a3c1-9a10fa7514c9-27f4e64e86ac08e8",
	"Action": "ForgotPassword"
}

The result contains an updated list of mechanisms whereby the password mechanism has been removed and a new mechanism called RESET has been added:

{
	"success": true,
	"Result": {
		... 
		"TenantId": "AAA3226",
		"Summary": "NewPackage",
		"SessionId": "1db90fe4-3b96-4c3e-a3c1-9a10fa7514c9-27f4e64e86ac08e8",
		"Challenges": [
			{
				"Mechanisms": [
					{
						"PromptSelectMech": "Email... @idaptive.app",
						"Name": "EMAIL",
						"AnswerType": "StartTextOob",
						"PartialAddress": "idaptive.app",
						"MechanismId": "1234ip1oimn4lIa4JW0Wu3BZRWSQXQtLuW9dPh7i1234",
						"PromptMechChosen": "Click the link in the email sent to xxxx@idaptive.app"
					}
				]
			},
					{
				"Mechanisms": [
					{
						"Name": "RESET",
						"AnswerType": "Text",
						"MechanismId": "1234wxOOZ31meg3XSB1EctdjX6mBBRJphuVX9jW30987"
					}
				]
			}
		],
		"Version": "1.0"
	},
	...
}

The RESET mechanism performs the password reset. This is covered below in steps 6 and 7.

Complete each the required authentication mechanism(s) using /Security/AdvanceAuthentication until you get to the RESET mechanism. Each of these mechanisms may require a user interface where the user can provide a response to the challenge. After the user fulfills these challenges, they will have the opportunity to change their password as described below.

For example:
```
POST /Security/AdvanceAuthentication

{
	"TenantId": "ABC1234",
	"SessionId": "1db90fe4-3b96-4c3e-a3c1-9a10fa7514c9-27f4e64e86ac08e8",
	"MechanismId": "1234ip1oimn4lIa4JW0Wu3BZRWSQXQtLuW9dPh7i1234",
	"Action": "StartOOB"
}
```
For out-of-bounds mechanisms, invoke the polling action repeatedly until the Result > Summary field in the response is returned as StartNextChallenge. For example:
```
POST /Security/AdvanceAuthentication

{
	"TenantId": "ABC1234",
	"SessionId": "1db90fe4-3b96-4c3e-a3c1-9a10fa7514c9-27f4e64e86ac08e8",
	"MechanismId": "1234ip1oimn4lIa4JW0Wu3BZRWSQXQtLuW9dPh7i1234",
	"Action": "Poll"
}
```
The Summary field in the response indicates the status of the challenges:
```
{
	"success":true,
	"Result":
	{
		"Summary":"StartNextChallenge"
	},
	...
}
```
Present a user interface requesting that the user enter a new password and confirmation password. Ensure that the password and confirmed password match.
Invoke the /Security/AdvanceAuthentication endpoint for the RESET mechanism and set the following in the body of the request:
- Action: set to Answer.
- TenantID: set to the tenant ID.
- SessionId: set the session ID.
- MechanismId: specify the mechanism ID of the RESET mechanism.
- Answer: set to the user's new password.
For example:
```
POST /Security/AdvanceAuthentication

{
	"TenantId": "ABC1234",
	"SessionId": "1db90fe4-3b96-4c3e-a3c1-9a10fa7514c9-27f4e64e86ac08e8",
	"MechanismId": "1234wxOOZ31meg3XSB1EctdjX6mBBRJphuVX9jW30987",
	"Action": "Answer",
	"Answer": "Pass4567"
}
```
Depending on the user's policy settings, the response may indicate that the user has been successfully logged in, which means the password has been changed, or the response may indicate that the user's password has been changed and that they need to log in again, as shown here:
```
{
	"success" : true,
	"Result" :
	{
		"ClientMessage" : "Password change was successful, please authenticate with your new credentials.",
		"Summary" : "NoncommitalSuccess"
	}
}
```

Reset a password after authentication

Using the CyberArk Identity authentication APIs, you also can reset a password on behalf of a user after that user has authenticated.

To reset a password in this scenario, invoke the UserMgmt/ChangeUserPassword endpoint, passing the old password and new password into the respective body parameters:

POST UserMgmt/ChangeUserPassword

{
	"newPassword": "ABC1234",
	"oldPassword": "DEF789"
}

The response indicates if the password reset is successful:

{
	"success": true,
	...
}