Request a reset password link

Update a user profile
Open Recipe

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.

ParameterTypeRequiredDescription
client_idstringAPI client ID used to authenticate the call. This client must be configured with the login_client feature, which gives it permission to use login and registration-based API endpoints. API client permissions may be configured by using the Configuration API.
flowstringName of the flow configured with the login experience you want to use. This parameter corresponds to the janrain.settings.capture.flowName JavaScript setting used in JavaScript SDK- based implementations.

The default flow provisioned with Registration applications is named the standard flow; if you have multiple flows, you can find a list of valid flow names using the Configuration API. You can omit this parameter if you configure the flow name in the default_flow_name setting for the API client used to make this call.
flow_versionintegerVersion number of the flow set in the flow parameter. This parameter corresponds to the janrain.settings.capture.flowVersion JavaScript setting used in JavaScript SDK-based implementations; however, this call will not accept a version of HEAD. Instead, you must specify the version number if you want to use the most recent version.

You can find a list of versions for your flow using the Configuration API. This parameter can be omitted if you you configure the flow version in the default_flow_version setting for the API client used to make this call.
formstringName of the form to be used to for generating the password reset email. This parameter determines the field names that must be included when submitting this API call.

The default form name for password reset configured for the standard flow is forgotPasswordForm, but you can find a list of valid forms and associated fields for your flow using the Configuration API.

This form name corresponds to the name of the JTL tag used for the associated form in JavaScript SDK-based implementations.
(form fields)stringName of the field used to generate the password reset email. You will use the field name as the key and the user input as the value for this parameter.

The default forgotPasswordForm configured for the standard flow uses the field signInEmailAddress. You can find a list of valid fields and associated forms for your flow using the Configuration API.

This field name corresponds to the JTL tag used for the email field in your forgot password form in JavaScript SDK-based implementations.
localestringCode for the language you want to use for the login experience. This determines the language for any error messages returned to you and the reset password emails sent to users. This parameter corresponds to the janrain.settings.language JavaScript setting used in widget-based implementations.

The default locale provisioned with the standard Registration flow is en-US. Other locales must be configured in your flow. You can find a list of valid locales for your flow using the Configuration API.
redirect_uristringMust match the value configured for the password_recover_url setting for the API client used to make this call. This parameter corresponds to the janrain.settings.capture.redirectUri JavaScript setting used in JavaScript SDK-based implementations.

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"
}