You can initiate a forgot password journey either when a user clicks on that user journey link in the /authorize screen, or you can take a user directly to that form by passing in a URL.

Integrating the forgot password screen via a URL requires further configuration.

Endpoint URL

The forgot password request consists of the base domain + the endpoint (/forgot-password) + parameters. Available parameters are listed below the example.

https://id.eu.nextreason.com/
forgot-password?
redirect_uri={{redirect_uri}}
&client_id={{client_id}}
&response_type=code
&state={{state}}
&scope=openid
&nonce={{nonce_value}}
&ui_locales=en-US
&code_challenge={{code_challange}}
&code_challenge_method=S256

Required Parameters

The following parameters must be included on every request.

Parameter	Description
`redirect_uri`	Configures the URL the user is redirected after a successful authentication. Important note: this URL must be included in the `redirect_uri_allowlist` client settings.
`client_id`	ID used to authenticate the API call. This client must be configured with the `login_client` feature.
`response_type`	Value that determines the authorization processing flow to be used, including what parameters are returned from the endpoints. We only support authorization code flow which means the only acceptable parameter is: `code`.
`state`	This `state` parameter is constructed by your application and included in the call to the hosted Next Identity service. It will remain unchanged and will be passed back to your application when the screen is redirected back. It is intended for use by your application to track user state. It should be an opaque value used to maintain state between the request and the callback. Typically for applications, Cross-Site Request Forgery (CSRF, XSRF) mitigation is done by cryptographically binding the value of this parameter with a browser cookie. This value is required on every call, but the hosted service does not use this value in any way, it is solely for use by the application. Doing so, the application can check and evaluate the value of the state parameter if it is correct or meets a specified criteria then perform expected actions or user journeys on the application-side.
`scope`	OpenID Connect requests must contain the `openid` scope value. If the `openid` scope value is not present, the behavior is entirely unspecified. Other scope values may be present. Scope values used that are not understood by an implementation should be ignored.

Optional Parameters

The following parameters are optional.

Parameter	Description
`prompt`	Space delimited, case sensitive list of ASCII string values that specifies whether the Authorization Server prompts the End-User for reauthentication and consent. The defined values are: `none` The Authorization Server must not display any authentication or consent user interface pages. An error is returned if a user is not already authenticated or the client does not have pre-configured consent for the requested claims or does not fulfill other conditions for processing the request. This can be used as a method to check for existing authentication and/or consent. `login` The Authorization Server should prompt the user for reauthentication. If it cannot reauthenticate the user, it must return an error, typically login_required.
`ui_locales`	Set the language to be displayed in the screen. Session cookie will save the locale setting sent for the first time, if this parameter is not present the latest language saved will be used to display the screen. It allows multiple locales and in case there's no configuration for the first one, it searches for the second one and so on. Since the `ui_locales` parameter is optional and will use the default_locale on settings if no value is present. See Localization for list of supported locales and the accepted values. The default country flag during mobile login or when changing the mobile number will be determined by the ui_locales in the query string parameters, if the mobile_query_default_flag is set in the configuration settings. If not, it will fall back to the mobile_default_country, then to the first value in the mobile_flag_countries setting, and finally to the default_locale.
`nonce`	String value used to associate a client session with an ID token and to mitigate replay attacks. The value is passed through unmodified from the Authentication Request to the ID Token. Sufficient entropy must be present in the nonce values used to prevent attackers from guessing values.
`environment_id`	The ID of the environment where the client is created. Each environment (for example, DEV, UAT or PROD) has their own environment_id.
`organization_id`	The ID of the organization in the Next Identity. Each Organization has their own organization_id.
`code_challenge`	Used in PKCE protocol.
`code_challenge_method`	Used in PKCE protocol.
`login_hint`	If this parameter value is passed with the call to the /authorize or /register endpoints, the email address or mobile number field on the hosted screen will be pre-filled. This applies to both email addresses and mobile phone numbers.

Response Handling

The forgot-password begins with your application directing users to the hosted /authorize endpoint. Then after clicking the forgot-password link, you will be prompted to enter the email address that you will reset the password.

After entering the email address, the user will receive a Reset Password email. The user will click the link in the email and will be redirected to the new window where they Create a New Password. User will then create a new password and click the Reset password button. After successfully resetting the password, the user will receive another email indicating that the password was updated successfully. The user can now use the new password created to login to the application.

Configuration Options

The attributes are customizable based on the requirements.

Configuration Option	Description
Custom Branding	Client has the option to add a brand logo, header logo, background image, favicon, button color and font style in the Authorize Page.

Error Handling

Code	Error	Cause
No code, error message only	Email address is not formatted correctly	Email format is incorect
No code, error message only	Complete your account registration	The account was not verified yet
No code, error message only	There was a security error with the form submission	The authorize page is left idle for 2 minutes
No code, error message only	Corrupt image	The assets, such as the logo or image, are pointing to a location that does not exist

Security Considerations

While the state parameter is not directly used within the register endpoint itself, it plays a critical role in ensuring the secure handling of the authorization process that leads to accessing the authorized page endpoint.

Integration

Forgot-password is already integrated in the authorize page. No other integration needed for Hosted Login Journeys.