Request a reset password link

Sends an email that includes a link with a one-time authorization code a user can click to set a new password. The destination URL for this link is configured in the password_recover_url setting for the API client used to make this call. Note that the time-to-live value for the link is managed by the recover_code_lifetime API client setting.

If you are not using the JavaScript widget at this URL, you need to use the oauth/token call to exchange the authorization code for an access token. You must use the same API client when making the oauth/forgot_password_native call to generate the code and when making the oauth/token call to consume it. If successful, you can proceed to use the oauth/update_profile_native call to update the user's password. If unsuccessful, this API can be used again to resend an email with a new code.

Authentication

No authentication is required to call this operation.

Base URL

The base URL for this operation is your Identity Cloud Capture domain; for example:

https://educationcenter.us-dev.janraincapture.com

Your Capture domain (also known as a Registration domain) can be found in Console on the Manage Application page.

Examples

Example: Trigger Forgot Password Email

This command sends a Forgot Password email to the user johndoe@example.com.

curl -X POST \
  --data-urlencode 'client_id=12345abcde12345abcde12345abcde12' \
  --data-urlencode 'flow=standard' \
  --data-urlencode 'flow_version=20190618143040022299' \
  --data-urlencode 'locale=en-US' \
  --data-urlencode 'redirect_uri=http://localhost' \
  --data-urlencode 'form=forgotPasswordForm' \
  --data-urlencode 'signInEmailAddress=johndoe@example.com' \
  https://my-app.janraincapture.com/oauth/forgot_password_native

Parameters

All parameters need to be configured as x-www-form-urlencoded body parameters.

Responses

200 OK

Successful Response

A successful call returns the following response:

{
  "stat": "ok"
}

Error - Email Does Not Exist

The example error response below indicates that the email address submitted isn't registered, so no email will be sent. The invalid_fields object includes a localized error message from the flow.

{
  "stat": "error",
  "code": 212,
  "error_description": "some inputs are invalid",
  "error": "no_such_account",
  "request_id": "hyhrbds6f4ws4vav",
  "invalid_fields": {
    "forgotPasswordForm": [
      "No account with that email address exists."
    ]
  }
}

Error - Field Validation Errors

The example error response below indicates that the email address submitted is registered for an account that has no password, usually because it was created with a social identity. No email will be sent in this case. The message attribute includes a localized error message from the flow. Your flow may be configured to bypass this error and send the email if desired.

{
  "stat": "error",
  "code": 540,
  "error_description": "an error was triggered in the flow",
  "error": "triggered_error",
  "request_id": "rspc2skdu7arex82",
  "message": "That account is social signin only."
}

Error - Missing Required Parameters

The example error response below indicates that one of the required parameters for the call wasn't included. The error message describes which parameter is missing.

{
  "stat": "error",
  "code": 100,
  "error_description": "missing arguments: flow",
  "error": "missing_argument",
  "request_id": "uyeem84bmqmnjuu4"
}

Error - Invalid Flow Value

The example error response below indicates that the value provided for one or more of the flow, flow_version, or locale parameters is invalid. Flow versions are unique across environments, so check that the version value included in the call is for the correct environment (that is, your development or production application).

{
  "stat": "error",
  "code": 500,
  "error_description": "could not find a flow named 'standard' with version '12345abc-1234-abcd-1234-12345abcde12' and locale 'en-US'",
  "error": "unexpected_error",
  "request_id": "murynd7fhpysq6um"
}

Error - Invalid API Client Permissions

The example error response below indicates that the API client used to make the call isn't configured with the login_client feature.

{
  "stat": "error",
  "code": 403,
  "error_description": "This client does not support log in and registration.",
  "error": "permission_error",
  "request_id": "y3sthb9dey6mv65e"
}