Gigya Job Openings

socialize.login REST

Skip to end of metadata
Go to start of metadata

Any reference to OpenID or OpenID Provider on this page is referring specifically to the OpenID OAuth 2.0 Protocol. For information pertaining to OpenID Connect, please see our OpenID Connect documentation.

Description

This API serves as an endpoint for user authentication using their social network / webmail account. This method requires user interaction. To log the user in, redirect the user to the specified URL and pass the required parameters. The login URL shows the login screen of the requested provider. In some cases, such as Facebook, users will also be asked to give the site permission to access their personal data.

When the login process completes (either successfully or with an error), Gigya server redirects the user to the URL defined in the redirect_uri parameter and appends response parameters.

The login operation is currently supported by the following providers: Amazon, Blogger, Facebook, FourSquare, GooglePlus, Instagram, Kakao, LINE, LinkedIn, Livedoor, Messenger, mixi, Naver, Netlog, Odnoklassniki, Orange France, PayPalOAuth, Tencent QQ, Renren, Sina Weibo, Spiceworks, Twitter, VKontakte, WeChat, WordPress, Xing, Yahoo, Yahoo Japan.

Read more in Using Gigya's REST API in compliance with OAuth 2.0.

 

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
x_providerstringThe provider which will be used for authenticating the user. The following values are currently supported for use with this parameter:
amazon,  blogger, facebook, foursquare, googleplus, instagram, kakao, line, linkedin, livedoor, messenger, mixi, naver, netlog, odnoklassnikiorangefrance, paypaloauth, qq, renren, sina, spiceworks, twitter, vkontakte, wechat, wordpressxing, yahoo, yahoojapan.
 Also SAML providers are supported - the format of the provider name is "saml-".
client_idstringThe Gigya API key. You may obtain a Gigya API key from the Site Dashboard page on Gigya's website.
redirect_uriURLThe URL to redirect to after the login completes. This must be verified against the registered domain for this API key.
response_typestringMay be either "token" or "code". See extended explanation below.
statestringA string that will be passed as another parameter to the redirect_uri after the login completes.
x_cidstringA context ID of the operation.
x_pending_registration BooleanThe default value of this parameter is 'true'. The default behavior - the account is not considered final until socialize.notifyRegistration is called. While being not-final the identities associated with this account can be connected to another account without causing an error.
If this parameter is set to 'false' - when a new user logs-in (registers), his new Gigya account is final immediately.
x_session_expirationintegerThis parameter defines the time in seconds that Gigya should keep the login session valid for the user. To end the session when the browser closes, please assign the value '0'. If this parameter is not specified, the session will be valid forever.
x_temporary_account BooleanThe default value of this parameter is false. Setting this parameter to true, indicates that the account is temporary and is only accessible with the associated access token. This means that it is not possible to access the same account, and get the same Gigya UID, again by using login. 
x_langstringDefines the language of Gigya's user interface and error message. For the list of supported languages, please refer to the languages table.
x_extraPermissionsstringA comma delimited list of extended permissions to request from the user. This parameter gives the possibility to request extended permissions in addition to the permissions that Gigya is already requesting.
Please refer to Facebook's extended permissions page, for the complete list of Facebook permissions.
For example, if you wish to RSVP to events on the user's behalf and to to send sms messages to the user, define: x_extraPermissions=" rsvp_event ,sms".
To request Google wallet permissions define: x_extraPermissions="wallet ".
Note: use the socialize.getRawData method to pull the extra data. 
x_forceAuthenticationBooleanThe default value of this parameter is 'false'. If it is set to 'true', the user is forced to provide their social network credentials during login - even if the user is already connected to the social network. This parameter is currently supported by Facebook, Twitter, and  Renren. Note that the behavior of the various social networks may be slightly different: Facebook expects the current user to enter their password, and will not accept a different user name. Other networks prompt the user to re-authorize the application or allow a different user to log in.
Note: this parameter is also named " forceAuthentication".
x_displayModestringThe display mode of the Facebook login page. The valid values are:
  • 'popup' (default) - displays Facebook's popup login dialog
  • 'page' - displays Facebook's full login page
  • 'touch' - used on smartphone mobile devices, like iPhone and Android
x_openIDUsernamestringThe username in the OpenID provider, if available. When this parameter is passed with a known OpenID provider, the username request screen is skipped.
x_openIDURLstringA URL template representing an OpenID user, where $USERNAME$ represents the placeholder for the username. For example: http://aol.com$USERNAME$. This parameter is required if  provider='openID'
x_openIDProviderLogostringA URL of the provider logo to display in the OpenID popup. This parameter is used only when provider='openID' and x_openIDURL is specified.
x_openIDProviderNamestringThe provider name to display in the OpenID popup. This parameter is used only when provider='openID' and x_openIDURL is specified.
x_googlePlayAppIDstringThe objective of this parameter is to support Over The Air app installs for Android devices during Google+ login. Set this parameter with the package name of your Android app (for example: "com.yourdomain.app"). As a result, after signing in with Google+, users have the option to send your Android app to their device instantly, without leaving your website. As a preliminary step you'll need to Utilize Google+ Native Android Sign-on on your Android app. The package name passed to this parameter is the same one you enter when enabling the Google+ API.
x_regSourcestring A string representing the source of the registration. This would typically be the URL where it took place.

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

When the login process completes (either successfully or with error), Gigya server redirects the user to the URL defined in the redirect_uri parameter and appends response parameters.

Response Type "token"

When the requested response_type is "token", the response parameters are appended as a URL fragment (following a # sign). The following parameters are appended, after a successful login:

FieldTypeDescription
access_token stringA Gigya session key. You may use this token to invoke Gigya's REST API methods. Pass this token as a parameter with each REST API method call. Read more in making an API call.
expires_innumberThe duration in seconds of the access token's lifetime. Note: This field is only returned when the token has an expiration time. If this field is not available then the token will not expire.
statestringThe state string passed by your application as parameter to the login end-point. (See table of Parameters above).
 x_newUserBooleanIndicates whether the user logging in is new. The parameter is returned only when it is set to "true".

 

The following parameter is appended, after an "account_pending_registration" error:

FieldTypeDescription
x_regTokenstringA ticket that is used to complete a registration process. The 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.

Response Type "code"

When the requested response_type is "code", the response parameters are appended as query string parameters (following a ? sign). The following parameters are appended, after a successful login:

FieldTypeDescription
codestringA Gigya authorization code. You may use this code to obtain an access token. The expiration time of this code is 2 minutes.
statestringThe state string passed by your application as parameter to the login end-point. (See table of Parameters above).

 

The following parameter is appended, after an "account_pending_registration" error:

FieldTypeDescription
x_regTokenstringA ticket that is used to complete a registration process. The 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 .

Error Response

If the login fails, Gigya will append the following parameters to the response URL (regardless of the response_type parameter value):

FieldTypeDescription
errorstringThe error code. For a complete list of error codes, see the Error Codes table below.
error_descriptionstringThe Gigya error code and error message (separated by a dash). For example: "500001 - Server error".
statestringThe state string passed by your application as parameter to the login end-point. (See table of Parameters above).

Error Codes

Error CodeDescription
invalid_requestThe request is missing a required parameter, includes an unknown parameter or parameter value, or is otherwise malformed.
invalid_client-idThe client identifier provided is invalid.
unauthorized_clientThe client is not authorized to use the requested response type.
redirect_uri_mismatchThe redirection URI provided does not match a pre-registered value.
access_deniedThe end-user or authorization server denied the request.
unsupported_response_typeThe requested response type is not supported by the authorization server.
account_pending_registrationThe registration process has not been finalized.
account_pending_tfa_verificationThe registration requires 2-factor authentication, and the device is not already in the verified device list for the account. 
account_pending_tfa_registrationThe registration requires 2-factor authentication, and the device is not already in the verified device list for the account.