Headless Identity APIs: Headless Forgot Password Flow for Customers and Partners

Your Client Requests a Password Reset

After your user starts the password reset process, your client sends a POST request to the headless forgot password endpoint on your Experience Cloud site (1).

Here’s the URI for the POST request.

/services/auth/headless/forgot_password

Include these headers in the request.

Include these parameters in the request body.

Here’s an example request for a public client that’s using a custom email template. It includes a reCAPTCHA token for security and an emailtemplate parameter with the developer name of a custom template.

POST /services/auth/headless/forgot_password HTTP/1.1
Host: MyDomainName.my.site.com
Content-Type: application/json
{
    "username":"lhansen@example.com",,
    "emailtemplate":"unfiled$public/SalesNewCustomerEmail",
    "recaptcha": "<recaptcha token>"
}

Here’s an example request for a private client that’s using the default email template. It includes an access token for security.

POST /services/auth/headless/forgot_password HTTP/1.1
Host: MyDomainName.my.site.com
Authorization: Bearer 00DR****************
Content-Type: application/json

{
    "username": "lhansen@example.com"
}

Here's an example request for a private client that uses headless user discovery.

POST /services/auth/headless/forgot_password HTTP/1.1
Host: MyDomainName.my.site.com
Authorization: Bearer 00DR****************
Content-Type: application/json

{
    "login_hint": "<user identifier such as email address, phone number, order number>",
    "customdata": {
        "firstName": "Lyle",
        "lastName": "Hansen"
    }
}

(Optional) Headless User Discovery Handler Finds the User

If you're using a headless user discovery handler, the handler takes the login_hint and customdata parameters and finds the associated user. The handler confirms that the email address or phone number for the user is verified.

For an example handler, see Auth.HeadlessUserDiscoveryHandler.

Salesforce Returns a Success Message and Verifies the Username

When Salesforce successfully receives the forgot password request, it sends a success message to the client (2). If you're not using a headless discovery handler, Salesforce then verifies that the username matches an account. If the username doesn’t match an account, the flow stops.

Here’s an example of a successful response.

{
    "status": "success",
    "status_code": "otp_sent"
}

If the request fails, Salesforce returns an error message describing the request. For most errors, Salesforce returns the error message in this format.

{
"status_code": "<error code>",
"<error name>": "<error description>",
"status": "failed"
}

For example, if the client uses the wrong type of HTTPS request, Salesforce returns this error response.

{
"status_code": "post_required",
"invalid request": "use a POST request",
"status": "failed"
}

For the invalid_recaptcha error code, the response includes additional information from Google’s reCAPTCHA service. Here’s how these responses are formatted.

{
"status_code": "invalid_recaptcha",
"invalid_request: "invalid reCAPTCHA token",
"status": "failed",
"recaptcha_response": {
    "success": <true or false>,
    "challenge_ts": <timestamp of the challenge in ISO format (yyyy-MM-dd'T'HH:mm:ssZZ)>,
    "hostname": "<host name of the client where the reCAPTCHA was solved>",
    "error-codes": [<error codes from Google reCAPTCHA...>]
    }
}

Here’s an overview of the error responses.

Salesforce Generates and Emails a One-Time Password

Salesforce verifies that an account with the user’s username exists in the system. If the account exists, it generates a one-time password and sends it in an email (3) to the email address on file. This email is generated using either the default email template or by referencing a custom template from the emailtemplate parameter in the initial request. For information about customizing the email template, see Customize Email Sent from Experience Cloud Sites.

Your Client Submits the New Password

When the client receives the success message from Salesforce, the client natively displays a password reset page to the user. This page must include fields for the one-time password and the user’s new password. The new password is subject to the Salesforce password requirements. After the user fills in these fields, the client sends another the username, OTP, and new password in another POST request to the forgot password endpoint (4).

Include these headers in the request.

Include these parameters in the request body.

Here’s an example request for a private client.

POST /services/auth/headless/forgot_password HTTP/1.1
Host: MyDomainName.my.site.com
Authorization: Bearer 00DR****************
Content-Type: application/json

{
"username": "lhansen@example.com",
"otp" : "123abc",
"newpassword" : "abcd1234"
}

Here’s a similar request for public clients that doesn’t include an access token. Because the reCAPTCHA token was sent in the initial request, it’s not required in this one.

POST /services/auth/headless/forgot_password HTTP/1.1
Host: MyDomainName.my.site.com
Content-Type: application/json
{
"username": "lhansen@example.com",
"otp" : "123abc",
"newpassword" : "abcd1234"
}

Salesforce Verifies the Passwords and Returns a Success Message

When Salesforce receives the password request, it verifies that the one-time password is valid, and it checks that the new password meets the requirements. If these two criteria are met, it sets the new password. After the password is changed, Salesforce sends a success message to the client (5). Here’s what the success message looks like.

{
    "status": "success",
    "status_code": "success"
}

Your client must notify the user that the change has been accepted and that they can log in with their new password.

Note

If the client sends an incorrect OTP or the new password doesn’t meet the standard Salesforce security requirements, the password reset fails. If the password reset fails, your client can make a set number of attempts to reset the password using the same OTP. You control the maximum number of attempts in your Experience Cloud settings. After too many failed attempts, your client must send a new initial reset password request so that a new one-time password can be generated and emailed to your user.

If the password change isn’t successful, Salesforce returns an error response in this format.

{
"status_code": "<error code>",
"<error name>": "<error description>",
"status": "failed"
}

Here’s an overview of the errors for this request.