Gigya Job Openings

accounts.resetPassword JS

Skip to end of metadata
Go to start of metadata

Description

This method starts the process to reset a user's password, either via email or directly. The email format is according to the templates defined in the site policy. For more information on the email format, please refer to  account.setPolicies  or to the  Password Reset Email  section of the User Management  Policies  guide.

 

Note: This method is also supported in our REST API. If you wish to execute this method from your server, please refer to

> accounts.resetPassword REST

Syntax

 

Note: If you plan on integrating Gigya's Accounts API, we highly recommend reading the Registration-as-a-Service Guide. Registration-as-a-Service (RaaS) is a premium platform that requires separate activation. If RaaS is not part of your site package, please contact Gigya by filling in a support form through the Console. You can access the support page by clicking Support on the upper menu after logging into the Gigya Console.

Resetting a User Password

There are three main options for password reset:

  • RaaS - The best option is to use the Reset Password screen of the LoginRegistration Screen-set. 
    For instructions on setting up your account for using the Reset Password Screen see the Email Templates documentation.

  • Via email - an email is sent to the user (automatically by Gigya *), containing a link to a "reset password" page 

    This option requires two accounts.resetPassword method calls:
    1. First call - when the user chooses to reset his password. Pass the user's loginID (username / email) as a parameter of this method, and optionally you may add  an email address.  Gigya sends the email to the first verified email address found in the user's account. If an  email  is passed as a parameter of this method, Gigya makes sure it matches an email address already associated with the account, and sends the password reset link to that email address. The email format and the reset link URL is defined in the site policy. See also the Password Reset Email guide.
       
    2. Second call - when the user clicks on the  reset link in the email he received from Gigya, and then submits his new password.  The reset link includes a token as a URL parameter, the format is: <reset page URL>?pwrt=<reset token>. The reset page should enable the user to submit a new password. With the submission, call the accounts.resetPassword method, pass the new password and the token as parameters (newPassword and passwordResetToken).
       
    * Note: To send the email by yourself and prevent Gigya from sending the email, use the sendEmail  parameter. When setting  sendEmail  to false Gigya does not send the password reset email to the user, instead, a passwordResetToken and the list of valid email addresses are returned in the response of this method. Use these fields to send the email to the user, then when the user submits the new password,  call the accounts.resetPassword method, pass the new password and the token as parameters.
     
  • Directly - resetting the password directly, i.e., without sending email. This option is used if the account does not contain an email address or when policies.passwordReset.requireSecurityCheck is set to trueThis option requires alternative means for verifying the ownership of the account. The means of verification can be either a secret answer or security fields (secretAnswer or securityFieldsparameter). Once verified, the password is reset directly, using the newPassword parameter.

    To implement the secretAnswer option, call this method first with passing only the loginID parameter. You will receive an error response with the  secretQuestion  field. Present the question to the user and ask him to enter the answer and the new password. Call the method again with
     the secretAnswer and newPassword  parameters.

Click the thumbnail below for a flowchart that describes the process.

 

Parameters

RequiredNameTypeDescription
loginIDstring

The existing account's loginID for identification. Can be a simple username or an email address. If it's an email address, it's the email address to which to send the password reset link, and it must already be associated with the specified account. Use this parameter when you first call this method.  

* You are required to pass only one of the parameters either loginID or passwordResetToken.

passwordResetTokenstring 

A token to be used for password reset in the password reset email. You can pass this parameter instead of loginID after it is returned in the  password reset email. If the token is found to be valid, the new password is set. The default token expiration time is 1 hour, and it can be changed in accounts.setPolicies in the passwordReset.tokenExpiration policy.

* You are required to pass only one of the parameters either loginID or passwordResetToken.

If passwordResetToken is passed then the newPassword parameter is also required.

newPasswordstringThe new password. Gigya will reset the password using this parameter only after verifying the ownership of the account, using either passwordResetToken (received with the password reset email), secretAnswer or securityFields parameters. In case loginID is passed (and not passwordResetToken) and  the account  includes an email address, this parameter is ignored and an email with a link to a "reset password" page is sent. The password property accepts unicode characters.
 
* This parameter is Required only in the following cases:
  • If passwordResetToken is passed.
  • If we do not have any email address defined for the user or if the policies.passwordReset.requireSecrutiyCheck property is set to true. In these case you are also required to pass either secretAnswer or securityFields  parameters.

Note:  If this parameter is passed then the method must be called using HTTPS.

secretAnswerstring

The user's answer to the secretQuestion. If we do not have any email address for the user or policies.passwordReset.requireSecurityCheck is true, the password may be reset directly by providing the newPassword parameter, in such case  you are required to pass either this parameter or securityFields. This field is hashed and can not be extracted.

* You are Required to pass one of the parameters either secretAnswer or securityFields, only in the following cases:

  • If the site policies defines passwordReset.requireSecurityCheck to be true.
  • If we do not have any email address already defined for the user. In this case the newPassword parameter is also required.
securityFieldsstring

One set of profile fields specified in the policy with their values provided by the user. If we do not have any email address for the user or policies.passwordReset.requireSecurityCheck is true, the password may be reset directly by providing the newPassword parameter, in such case  you are required to pass either this parameter or secretAnswer.

* You are Required to pass one of the parameters either secretAnswer or securityFields, only in the following cases:

  • If the site policies defines passwordReset.requireSecurityCheck to be true.
  • If we do not have any email address already defined for the user. In this case the newPassword parameter is also required.
emailstringIf specified, allows sending a password reset link to an unverified email address that is not the current loginID, as long as it is already defined in the account. 
langstring

The language specified for emails. If a template was defined for that language, the email sent to the user will be in that language. Otherwise, the language used in the email is taken from the locale field of the site identity, if available.

This parameter is only valid if the profile.locale is not set.

sendEmailBoolean

The default is true. When set to false Gigya does not send the password reset email to the user, instead, the passwordResetToken and the list of valid email addresses are returned in the response of this method (see passwordResetToken and emails fields in the method response below).

This parameter is not supported in the Web SDK.

format string Determines the format of the response. The options are:
  • json (default)
  • jsonp - if the format is jsonp then you are required to define a callback method (see parameter below).
callback string This parameter is required only when the format parameter is set to jsonp (see above). In such cases this parameter should define the name of the callback method to be called in the response, along with the jsonp response data.
context string/JSON This parameter may be used to pass data through the current method and return it, unchanged, within the response.
dontHandleScreenSet Boolean This parameter may be used in order to suppress the showing of screen-sets as a result of API calls. Default is false.
httpStatusCodes Boolean The default value of this parameter is false, which means that the HTTP status code in Gigya's response is always 200 (OK), even if an error occurs. The error code and message is given within the response data (see below). If this parameter is set to true, the HTTP status code in Gigya's response would reflect an error, if one occurred.

Response Data

FieldTypeDescription
 
errorCode integer The result code of the operation. Code '0' indicates success, any other number indicates failure. For a complete list of error codes, see the Error Codes table.
errorMessage string A short textual description of an error, associated with the errorCode, for logging purposes. This field will appear in the response only in case of an error.
errorDetails string This field will appear in the response only in case of an error and will contain the exception info, if available.
fullEventName string The full name of the event that triggered the response. This is an internally used parameter that is not always returned and should not be relied upon by your implementation.
callId string Unique identifier of the transaction, for debugging purposes.
time string The time of the response represented in ISO 8601 format, i.e., yyyy-mm-dd-Thh:MM:ss.SSSZ or
statusCode integer The HTTP response code of the operation. Code '200' indicates success.
This property is deprecated and only returned for backward compatibility.
statusReason string A brief explanation of the status code.
This property is deprecated and only returned for backward compatibility.

 

secretQuestionstringThis field  is returned only if there is a security verification failed error (code #400050).
passwordResetTokenstring

This field is returned only if,  in the method call, you set the sendEmail parameter to false (see description of the parameter above).
A token to be used for password reset in the password reset email. 

If this method is used repeatedly on the same user, any previously sent tokens are revoked and only the last token sent will allow the user to reset their password.

emailsJSON objectThis field is returned only if, in the method call, you set the sendEmail parameter to false (see description of the parameter above).
The email addresses belonging to the user. This includes the following fields:
  • verified  - an array of strings representing the user's verified email addresses
  • unverified  - an array of strings representing the user's unverified email addresses.
UIDstringThe user ID of the user whose password was changed. This field is only returned when the password is changed, not in calls that send an email or return a secret question.

A field that does not contain data will not appear in the response.

Response Example

{
  "statusCode": 200,
  "errorCode": 0,
  "statusReason": "OK",
  "callId": "ddb3f8e144c84cb5b1bc5f010bddab2b",
  "time": "2015-03-22T11:42:25.943Z"
}

 



  • No labels