Gigya Job Openings

accounts.notifyLogin REST

Skip to end of metadata
Go to start of metadata

Description

This method notifies Gigya of an external login that happened outside of the Accounts system.
The notifyLogin call registers a new user in the Accounts service, in case the siteUID parameter provided is new, or reconnects a returning user in case the siteUID already exists in our records.

Synchronizing the session to the client-side

When receiving the response from this API, please make sure to create a session cookie, using data contained in the returned sessionInfo object, so as to maintain the client application synchronized with the user state. The response includes data fields specifying the name, content and location of the session cookie. Please make sure that the page following the login includes Gigya's library i.e., gigya.js, in order for Gigya to read the cookie before it expires. If you are using an ajax-based site login (no page refresh after logging in), make a call to socialize.refreshUI after setting the session cookie so that Gigya is able to process the authorization before it expires.

Adding Connections

The notifyLogin call registers a new user in the Gigya service when the siteUID parameter provided is new, or reconnects a returning user when the siteUID already exists in our records.

It is essential to call notifyLogin if you are enabling users in your site to add connections to social networks via Gigya (using socialize.showAddConnectionsUI or socialize.addConnection). The notifyLogin call allows Gigya to associate the current user's social connections with the User ID you have designated to this user.

This association has several benefits:

  • Any connections the user makes to social networks will be associated with the site account. The social graph will be automatically made available the next time the user logs in to the site.
  • In calls to socialize.getUserInfo and socialize.getFriendsInfo Gigya will return your own User ID as the UID for this user.
  • Gigya will set the isSiteUser flag for this user to "true", thus even if this user is referred to as a friend of another user you can easily tell he is a user of your site and not just a friend of the visiting user.

Read more about integrating Gigya's Social Login and the implementation flow in our Social Login guide.

When calling notifyLogin on a user that has not finalized registration, if the user's account already contains all required fields, the isRegistered flag will set to true.

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.

Request URL

Where <Data_Center> is:
  • us1.gigya.com - For the US data center.
  • eu1.gigya.com - For the European data center.
  • au1.gigya.com - For the Australian data center.
  • ru1.gigya.com - For the Russian data center.
  • cn1.gigya-api.cn - For the Chinese data center.

If you are not sure of your site's data center, see Finding Your Data Center.

Parameters

RequiredNameTypeDescription
siteUIDstring

A unique identifier used by your site to identify the user. You may use the user's account ID that you have designated for this user in your database.
Note: the parameter accepts only ASCII characters (not Unicode) and up to 252 characters. If you use this parameter, providerSessions  is Optional.

*     You are required to pass at least one of the parameters siteUID  and/or  providerSessions .

providerSessionsJSON object

This parameter gives the option to pass to Gigya, session information obtained directly from a social network, so it can be used for making API calls to the social network. The value of this parameter is a JSON object with reference to other objects. The field names of the main object are the names of the provider to set the session information for. The sub-objects contain the session information. For example:

{ 
    "facebook" : { 
		"authToken" : "9187391837918237" 
	},
    "yahoo" : { 
		"authToken" : "kjhd0ukjhuwd", 
		"tokenSecret" : "aALJSIjlSyug", 
        "tokenExpiration": 123890983 
	}
} 

Note, each provider requires a different set of fields for making API calls.
The provider field names may be: 'google', 'facebook', googleplus, 'twitter', 'yahoo', 'microsoft', 'line', 'linkedin', 'qq', 'renren', 'sina' , vkontakte , wechat (Note: messenger has been replaced by microsoft, however, for backward compatibility, either can be used) .
The sub-objects' fields are:

  • authToken : The session authentication token.
    Note: For Facebook this member should hold the Facebook Session Key.
  • tokenSecret : The session token secret.
    Note: For Facebook this member should hold the Facebook sessionSecret.
  • tokenExpiration : The absolute time when the session token expires in UNIX time format.
  • sessionHandle : The session handle encoded in BASE64.
  • sessionHandleExpiration : The absolute time when the session expires in UNIX time format.

Note: If this parameter is specified the call must be done over HTTPS and the siteUID parameter becomes optional.

*     You are required to pass at least one of the parameters siteUID  and/or  providerSessions .

sessionExpirationinteger

This parameter defines the length of time that Gigya should keep the user's login session valid. It can be configured via Global Configuration, via an individual API call, or left empty. If no value is specified, the default values are 0 or -2, depending on whether your site uses RaaS or not (see below); Global configuration overrides the default, and setting the value via individual API calls override the global configuration. 

The expected values are:

  •  0 - Session expires when the browser closes. This is the default behavior when RaaS is enabled in your site. This behavior is dependent upon the browser's cookie handling procedures, i.e., Chrome keeps processes running in the background even after the browser is technically closed, this keeps the cookies valid until the background processes are terminated.

  • -1 - Session ends after a 60 second period; Gigya gives you the option of creating a cookie that is stored on the site visitor's client (browser), allowing the site to control the session length within this 60 second window, after which the session is terminated if no cookie is found. A typical use case is when the session could include sensitive data (such as credit card details), and the session should be short, with the option of restarting the duration when users perform actions. Useful if you always set the session expiration via individual API methods or with each request, such as when the site session is controlled by a CMS (e.g., Drupal). For additional information, see how to define a session expiration cookie.

  • -2 - Session is valid forever. This is the default behavior when RaaS is not enabled in your site. 

  • Any custom integer - Defines the number of seconds the session is active, e.g., 3600  (one hour). 


skipValidationBooleanDefault is false. If set to true, the server will not perform any validation on the user and will not return any pending state errors and will not check for any registration requirements for the end user. This parameter can only be used over HTTPS.
cidstring
A string of maximum 100 characters length. The CID sets categories for transactions that can be used later for filtering reports generated by Gigya in the "Context ID" combo box. The CID allows you to associate the report information with your own internal data. For example, to identify a specific widget or page on your site/application. You should not define more than 100 different context IDs.
targetEnvstringThis parameter defines your client side environment, which in return determines the server response data fields. The default value of this parameter is "browser", which means that by default you receive cookie-related data in the response. 
If your client runs on a mobile:
If you are calling this method using a Mobile SDK since version 2.15.6, this parameter is automatically set to "mobile" (there is no need to set it manually). In any other case, you should set this parameter to be "mobile". 
As a result of setting the parameter to "mobile" the server response data fields will include: sessionToken and sessionSecret (instead of cookie related data). In such case, you should send the sessionToken and sessionSecret to your mobile client. On your client side, call GSAPI.setSession (using the Mobile SDK) to save them in the app's storage.
regSourcestring

Records the source of the registration. The default value is the URL of the current page but it can be any string value. regSource is stored in the account and can be used by verification emails to determine which page should be opened (see accounts.set Policies). Can also be set via the Global Conf object.

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.

The following parameters are Required   only when calling the method from client side (e.g., using a  Mobile SDK ): 

UIDSigstringThe UIDSig is an HMAC-SHA1 signature proving the authenticity of the data. The signature construction should be implemented on your server side. You can read more in Constructing a Signature .
UIDTimestampstringThe UIDTimestamp is the current GMT time when request is made. The expected format is the Unix time format (i.e. the number of seconds since Jan. 1st 1970). Gigya will check the time difference between the timestamp and the time on Gigya's server when this request is received. If the time difference is more than 5 minutes, the request is considered forged. Please make sure that the UIDTimestamp holds the same timestamp used in the construction of the UIDSig parameter. You can read more in Constructing a Signature .

Authorization Parameters

Each REST API request must contain identification and authorization parameters.

Some REST APIs may function without these authorization parameters, however, when that occurs, these calls are treated as client-side calls and all client-side rate limits will apply. In order to not reach client-side IP rate limits that may impact your implementation when using server-to-server REST calls, it is Recommended Best Practice to always sign the request or use a secret. A non-exhaustive list of REST APIs that this may apply to are as follows:

  • accounts.login
  • socialize.login
  • accounts.notifyLogin
  • socialize.notifyLogin
  • accounts.finalizeRegistration
  • accounts.linkAccounts

Please refer to the Authorization Parameters section for details. 



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.

 

   
UID string The unique user ID. This user ID should be used for login verification. See User.UID for more information.
UIDSignature string The signature that should be used for login verification. See User.UID for more information.
signatureTimestamp string The GMT time of the response in UNIX time format, i.e., the number of seconds since Jan. 1st 1970. The timestamp should be used for login verification. See User.UID for more information.
created string The UTC time the account was created in ISO 8601 format, e.g., "1997-07-16T19:20:30Z".
createdTimestamp integer The UTC time the account was created in Unix time format including milliseconds (i.e., the number of seconds since Jan. 1st 1970 * 1000).
data JSON object Custom data. Any data that you want to store regarding the user that isn't part of the Profile object.
emails JSON object 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.

Note: emails must be specified explicitly in the include parameter in order to be included in the response.

identities array An array of Identity Objects, each object represents a user's social identity. Each Identity Object contains imported data from a social network that the user has connected to.
Note: You must explicitly specify identities within the include parameter for them to be included in the response: identities-active , identities-all, or identities-global to return only active identities, all identities of a site, or all identities of a site group, respectively.
   

Be advised that if a user registers to your site using a Social Identity, then goes through the Forgot Password flow, a Site Login is added to their account, however, a Site Identity is not. A Site Identity can only be created when accounts.setAccountInfo is called on the user's account.

iRank integer Influencer rank of the user. This property is deprecated and will always return 0.
isActive Boolean Indicates whether the account is active. The account is active once the user creates it even without finalizing it. The account can be deactivated, but it will still be registered if the registration process has been finalized. If isActive==false the user cannot log in, however any currently active sessions remain valid.
isLockedOut Boolean Indicates whether the account is currently locked out. This parameter is not included in the response by default, and is not returned at all from accounts.search. If you wish to include it in a response, specify it as a value of the include parameter.
isRegistered Boolean Indicates whether the user is registered. The user is registered once his registration has been finalized.
isVerified Boolean Indicates whether the account email is verified.
lastLogin string The time of the last login of the user in ISO 8601 format, e.g., "1997-07-16T19:20:30Z".
lastLoginLocation JSON object The user's last login location. This includes the following fields:
  • country - a string representing the two-character country code.
  • state - a string representing the state, where available.
  • city - a string representing the city name.
  • coordinates - an object containing:
    • lat - a double representing the latitude of the center of the city.
    • lon - a double representing the longitude of the center of the city.
lastLoginTimestamp integer The UTC time of the last login of the user in Unix time format including milliseconds (i.e., the number of seconds since Jan. 1st 1970 * 1000).
lastUpdated string The UTC time when user profile, preferences, or subscriptions data was last updated (either full or partial update) in ISO 8601 format, e.g., "2017-07-16T19:20:30Z".
lastUpdatedTimestamp integer The UTC time when the last update of the object occurred (either full or partial update) in Unix time including milliseconds, based on when the 'lastUpdated', 'Report AccountsFirstLogin' or 'AccountsReturnedLogin' events are fired.
loginIDs JSON object The user's login identifiers. This includes the following fields:
  • username - a string representing the username
  • emails - an array of strings representing email addresses
  • unverifiedEmails - an array of strings representing email addresses that were not validated

Note: loginIDs must be specified explicitly in the include parameter in order to be included in the response.

loginProvider string The name of the provider that the user used in order to login.
oldestDataUpdated string The UTC time when the oldest data of the object was refreshed in ISO 8601 format, e.g., "1997-07-16T19:20:30Z".
oldestDataUpdatedTimestamp integer The UTC time when the oldest data of the object was refreshed in Unix time format including milliseconds (i.e., the number of seconds since Jan. 1st 1970 * 1000).
password JSON object The user's Site account password details. Includes the following:
  • hash - the hashed password
  • hashSettings - object includes:
    • algorithm - Represents the hash algorithm used to encrypt the password.
    • rounds - Represents the number of iterations to perform the hashing.
    • salt - Represents the BASE64 encoded value of the salt.
    • format - Represents the template for merging clear-text passwords. This is only returned if the pwHashFormat parameter was set during account import and until the user's first login to Gigya (when the user's password is rehashed per the site's settings). See the RaaS Import Guide for additional information.
UIDSignature string This property is deprecated in server to server REST calls! The signature that should be used for login verification. See User.UID for more information.
signatureTimestamp string This property is deprecated in server to server REST calls! The GMT time of the response in UNIX time format, i.e., the number of seconds since Jan. 1st 1970. The timestamp should be used for login verification. See User.UID for more information.
phoneNumber string The Phone Number ID, if the account uses Phone Number Login.
preferences Preferences object The user's preferences information as described in the Preferences Object. To have this data returned in the response it must be specifically requested using the include parameter.
profile Profile object The user's profile information as described in the object. The profile is returned in the response by default, but if the include parameter is used to specify other fields that should be provided in the response, the profile must also be specified explicitly in the include parameter.
rbaPolicy JSON object The current RBA Policy defined for the specified user. Properties include:
  • riskPolicy - Determines the rule set from the defined rulesSets configured in accounts.rba.setPolicy or one of the default policies.
  • riskPolicyLocked - Determines whether the user can change their own riskPolicy. If true, only an admin can change the user's riskPolicy.
registered string The UTC time when the isRegistered parameter was set to true in ISO 8601 format, e.g., "1997-07-16T19:20:30Z".
registeredTimestamp string The GMT time when the isRegistered parameter was set to true in UNIX time format, including milliseconds.
regSource string A string representing the source of the registration. Can be used to set varying destination pages in accounts.setPolicies.
socialProviders string A comma-separated list of the names of the providers to which the user is connected/logged in.
subscriptions Subscriptions Object The user's subscription information.
userInfo User object The Gigya User object. This property is deprecated and should not be relied upon.
verified string The UTC time when the isVerified parameter was set to true in ISO 8601 format, e.g., "1997-07-16T19:20:30Z".
verifiedTimestamp string The GMT time when the isVerified parameter was set to true in Unix time format including milliseconds (i.e., the number of seconds since Jan. 1st 1970 * 1000).
regTokenstringA ticket that is used to complete a registration process. A new regToken is returned when there is a pending registration error, which occurs when the user did not complete the registration process, or there are missing fields in the user profile data that were defined as "required" in the Schema.
sessionInfoJSON object

An object containg session information. The content of this object depends on the targetEnv parameter (see above).
By default, if the targetEnv parameter is not set (your client environment is web), the sessionInfo object contains the the following string fields: cookieName and cookieValue.
Please create a session cookie with the name and value specified by these fields.
Alternatively, if  the targetEnv parameter is set to "mobile" (your client runs on a mobile), the sessionInfo object contains the the following string fields: sessionToken and sessionSecret. Please send these fields to your mobile client. On your client side, call GSAPI.setSession (using the Mobile SDK) to save them on the app's storage.

See notifyLogin Troubleshooting Tips for additional information.

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

 

Response Example

{
  "UID": "e862a450214c46b3973ff3c8368d1c7e",
  "UIDSignature": "Z4R82fBx4ERq85LA3g3qTmf0GPE=",
  "signatureTimestamp": "1344413375",
  "loginProvider": "site",
  "isRegistered": true,
  "registeredTimestamp": 1344415327000,
  "registered": "2012-08-08T08:42:07Z",
  "isActive": true,
  "isVerified": true,
  "verifiedTimestamp": 1344413279133,
  "verified": "2012-08-08T08:07:59.133Z",
  "socialProviders": "site",
  "profile": {
    "email": "Joe@hotmail.com",
    "firstName": "Joe",
    "lastName": "Smith",
    "age" : "31",
    "gender" : "m",
    "country" : "US"
  },
  "identities": [
    {
      "provider": "site",
      "providerUID": "e862a450214c46b3973ff3c8368d1c7e",
      "isLoginIdentity": false,
      "gender": "",
      "email": "tanya@gigya-inc.com",
      "allowsLogin": false,
      "isExpiredSession": false,
      "lastUpdated": "2012-08-08T08:07:59.133Z",
      "lastUpdatedTimestamp": 1344413279133,
      "oldestDataUpdated": "2012-08-08T08:07:59.133Z",
      "oldestDataUpdatedTimestamp": 1344413279133
    }
  ],
  "created": "2012-08-08T08:07:59.128Z",
  "createdTimestamp": 1344413279128,
  "lastLogin": "2012-08-08T08:09:17Z",
  "lastLoginTimestamp": 1344413357000,
  "lastUpdated": "2012-08-08T08:07:59.133Z",
  "lastUpdatedTimestamp": 1344413279133,
  "oldestDataUpdated": "2012-08-08T08:07:59.133Z",
  "oldestDataUpdatedTimestamp": 1344413279133,
  "statusCode": 200,
  "errorCode": 0,
  "statusReason": "OK",
  "callId": "904c170142754fcfb44e7063baa32406",
  "time": "2015-03-22T11:42:25.943Z"
}