The following document is a guide for using Gigya's REST API conforming with the OAuth 2.0 standard.
The REST API Reference provides specification to the various REST API methods supported by Gigya.
Note: Gigya offers a set of SDKs that wrap around Gigya's REST API. The SDKs make it simple to integrate Gigya's service for various development environments. Check out our SDKs documentation and find out if there is an SDK available for your preferred language. Otherwise, please continue with this guide and learn how to use our REST API directly.
The OAuth 2.0 Protocol
The OAuth 2.0 specifies an authorization flow prior to using the REST API methods. Your application must obtain authorization in order to access the user's social profile or perform social activities, such as publishing newsfeed.
OAuth 2.0 supports many options in the authorization flow for different use cases. In this section we describe the main use cases and their corresponding flows.
Use case 1 - Smart Client Application Flow
This use-case applies to Social Login using Gigya's socialize APIs (without RaaS).
This is the use case of a smart client application, such as mobile or desktop client application. In this case the client application communicates directly with our REST API.
Implementation Steps
- Login the user via the Gigya service, by redirecting the user to our login end-point URL. Pass the response_type=“token” parameter. Read more in the Login end-point section below.
- In the Login response you will receive the access_token. This token is your authorization ticket for accessing the current user's social profile.
- Pass the access_token with each REST API method call, related with the current user. Read how to make an API call below.
- Receive REST API method response.
Use Case 2 - Direct Server to Server Flow
This use-case applies when using Gigya Registration-as-a-Service (RaaS).
In this use case the REST API calls are not bound to an active user (there is no active session). There are two options in this use case:
- For methods which must be associated to a specific user (such as setStatus, getFriendsInfo, etc.), retrieve the user's UID from your DB and pass it as a parameter.
- For methods which are not associated with a user (such as reports.getSocializeStats), there is no need to pass a UID parameter.
Implementation Steps
Your Client Application:
- Login the user via the Gigya service, using our Web SDK method calls: socialize.login or socialize.notifyLogin. You may also use our ready made Login add-on.
In the Login response you will receive the User object.
Notes:
- To learn how to implement client side login using our Web SDK, see Social Login.
- An alternative implementation to steps 1 & 2 is to use the Login end-point to log in the user (as described in use case 1), and then use the socialize.getUserInfo to retrieve the User data.
Pass the User object to your server application.
Your Server Application:
- Obtain the access_token using the getToken end-point and pass the grant_type=“none” parameter. The getToken method must be called over HTTPS. Read more in the section below.
- Receive the getToken method response. The response will contain the access_token. Note that in this use case, the token is not related to a specific user.
- Pass the access_token with each REST API method call. If the method call is associated with a specific user, pass the user's UID as a parameter. Read how to make an API call below.
- Receive REST API method response.
Alternate Use Case 2 - Hybrid Client/Server Flow
As above, in this case you use both the client and server applications to communicate with Gigya's REST and Client API's, but in reverse order. First the server requests an access token, then that token is set as a global Configuration object when loading the Gigya Web SDK.
Implementation steps
- Obtain the access_token using the getToken end-point and pass the grant_type=“none” parameter. The getToken method must be called over HTTPS. Read more in the section below.
- Receive the getToken method response. The response will contain the access_token.
Your Client Application:
Load the Gigya Web SDK, passing the access_token as a global Configuration object. For example:
// Load Gigya dynamically with an oauth_token function loadGigya(accessToken){ var s = document.createElement('script'); s.type = 'text/javascript'; s.async = true; s.src = "http://cdn.gigya.com/js/gigya.js?apikey=<Your-API-Key>"; s.text = '{oauth_token: "' + accessToken + '"}'; document.getElementsByTagName('head')[0].appendChild(s); }
- Gigya services will now be loaded with the user already logged in.
Use Case 3 - Web Server Flow
This use-case applies to Social Login using Gigya's socialize APIs (without RaaS).
These use cases may be useful for web sites that require extra security, for example, eCommerce sites. In this use case the server application performs the REST API calls. Since it is not safe to transfer the access_token from the client to the server, we will use a code instead. Your server will use the code to retrieve the access_token over HTTPS.
Implementation Steps
Your Client Application:
- Login the user via the Gigya service, using the Login Plugin or the socialize.login API method of our Web SDK. Important: Set the authCodeOnly parameter to true.
- In the onLogin event data (or in the socialize.login API method response) you will receive the authCode.
- Pass the authCode to your server application.
(Alternatively, you may redirect the user to our login end-point URL. Pass the response_type=“code” parameter. Receive the code in the response, and pass it to the server. Read more in the Login end-point section below.)
Your Server Application:
- Obtain the access_token using the getToken end-point. Pass the code as a parameter and the grant_type=“authorization_code” parameter. The getToken must be called over HTTPS. Read more in the section below.
- Receive the getToken method response. The response will contain the access_token. This token is your authorization ticket for accessing the current user's social profile.
- Pass the access_token with each REST API method call, related to the user. Read how to make an API call below.
- Receive the REST API method response.
The Login End-Point
Gigya provides an end-point for the user to log in using the user's social network or webmail account. This login end-point 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, Gigya will redirect the user to the specified URL.
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.
The Login End-Point URL
https://socialize.<Data_Center>/socialize.login
us1.gigya.com
- For the US data center.eu1
- For the European data center..gigya.com
au1
- For the Australian data center..gigya.com
ru1
- For the Russian data center..gigya.com
cn1
- For the Chinese data center..gigya-api.cn
If you are not sure of your site's data center, see Finding Your Data Center.
Code Example
In the following example, clicking the button opens the URL in a new window:
<script type="text/javascript"> function open_win() { window.open("https://socialize.us1.gigya.com/socialize.login?client_id=3_mK2cmEzLkzhqe4MUrtPncxbv4wKsYAhsew0iVwhVUls3c_Jx_HLX434jAVpq5M_W&"+"redirect_uri=http%3A%2F%2Fdevelopers.gigya.com%2Fdisplay%2FGD%2FOAuth%2B2%2BLogin%2BSuccess%2BPage&x_provider=facebook&response_type=token"); } </script> <form> <input type=button value="Login to Facebook" onclick="open_win()"> </form>
Working Example
(Note that the Logout button, above, will only log you out from Gigya, and not any social networks you are currently connected to).
Parameters
Required | Name | Type | Description |
| x_provider | string | The 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, odnoklassniki, orangefrance, paypaloauth, qq, renren, sina, spiceworks, twitter, vkontakte, wechat, wordpress, xing, yahoo, yahoojapan. |
| client_id | string | The Gigya API key. You may obtain a Gigya API key from the Site Dashboard page on Gigya's website. |
| redirect_uri | URL | The URL to redirect to after the login completes. This must be verified against the registered domain for this API key. |
| response_type | string | May be either "token" or "code". See extended explanation below. |
| state | string | A string that will be passed as another parameter to the redirect_uri after the login completes. |
| x_cid | string | A context ID of the operation. |
| x_pending_registration | Boolean | The default value of this parameter is false. If set to true, 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. |
| x_temporary_account | Deprecated | Gigya no longer supports temporary users. |
| x_lang | string | Defines the language of Gigya's user interface and error message. For the list of languages supported, please refer to the languages table. |
Response
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.
The login end-point defines two types of responses: "token" or "code". The "token" response type is used in Use case 1 and the "code" response type is used in Use case 3. Please, specify the response type using the response_type required parameter .
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:
Field | Type | Description |
access_token | string | A 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 how to make an API call below. |
expires_in | number | The 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. |
state | string | The state string passed by your application as parameter to the login end-point. (See table of Parameters above). |
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:
Field | Type | Description |
code | string | A Gigya authorization code. You may use this code to obtain an access token. The expiration time of this code is 2 minutes. |
state | string | The state string passed by your application as parameter to the login end-point. (See table of Parameters above). |
Error Response
If the login fails, Gigya will append the following parameters to the response URL (regardless of the response_type parameter value):
Field | Type | Description |
error | string | The OAuth 2.0 error code. For a complete list of error codes, see the OAuth 2.0 Error Codes table below. |
error_description | string | The Gigya error code and error message (separated by a dash). For example: "500001 - Server error". For the complete list of Gigya error codes and descriptions, please refer to the Gigya Error Codes table. |
state | string | The state string passed by your application as parameter to the login end-point. (See table of Parameters above). |
OAuth 2.0 Error Codes
Error Code | Description |
invalid_request | The request is missing a required parameter, includes an unknown parameter or parameter value, or is otherwise malformed. |
invalid_client | The client identifier provided is invalid. |
unauthorized_client | The client is not authorized to use the requested response type. |
redirect_uri_mismatch | The redirection URI provided does not match a pre-registered value. |
access_denied | The end-user or authorization server denied the request. |
unsupported_response_type | The requested response type is not supported by the authorization server. |
Getting an Access Token
This method retrieves an access token.
Notes:
- You may invoke the getToken method only over HTTPS. Calls over HTTP will be rejected.
- Please use POST with this request and pass all parameters in the body of the request.
Your Application Identification
The getToken method requires an API Key and a Secret Key which are obtained from the Site Dashboard page on Gigya's website. The Secret Key must be kept secret and never transmitted to an untrusted client or over insecure networks. There are two ways in which you may pass these keys with the getToken method:
- Using HTTP Basic Authorization header (preferred method) :
The Authorization value should be constructed as follows: BASE64( <Api Key> ":" <Secret> ).
For example:
POST /token HTTP/1.1
Host: server.example.com
Authorization: Basic PUT-YOUR-KEYS-STRING-HERE
Content-Type: application/x-www-form-urlencoded
- Using query parameters:
- client_id - The Gigya API key
- client_secret - The Gigya Secret Key
The getToken Request URL
https://socialize.<Data_Center>/socialize.getToken
us1.gigya.com
- For the US data center.eu1
- For the European data center..gigya.com
au1
- For the Australian data center..gigya.com
ru1
- For the Russian data center..gigya.com
cn1
- For the Chinese data center..gigya-api.cn
If you are not sure of your site's data center, see Finding Your Data Center.
Parameters
The behavior of the getToken method is determined by the grant_type parameter.
There are two types of behaviors: "grant_type=none" or "grant_type=authorization_code". The "none" grant type is used in Use case 2 and the "authorization_code" grant type is used in Use case 3. The set of parameters which the method receives depends on the grant type.
Parameters for grant_type=authorization_code:
Required | Name | Type | Description |
| grant_type | string | "authorization_code" |
| code | string | The verification code received from the login response (Read more in Use case 3 flow).
|
| redirect_uri | string | This parameter is used for validation. The URL must be the same redirect_uri provided in the login request (Read more in Use case 3 flow). |
| regSource | string |
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. |
Parameters for grant_type=none:
(You may use a user or application key and corresponding secret only using this method)
Required | Name | Type | Description |
| grant_type | string | "none" |
| x_siteUID | string | You may provide the UID of the user that has been logged in by your site. This will generate an access token associated with the user and will allow you to invoke REST API methods, without passing the UID parameter. When passing this parameter, this method becomes equivalent to the socialize.notifyLogin API method, notifying the Gigya service that the user has been logged-in by the site. Note that any providerSessions parameter will be ignored. |
| x_userInfo | JSON string | This parameter is relevant only if the x_siteUID parameter (see above) is specified. x_siteUID=12345&userInfo;={firstName:"David", gender:"male", age:30} |
| x_sessionExpiration | integer | The time in seconds that Gigya should keep the session valid for the user. To end the session when the browser closes, assign the value '0'. If this parameter is not specified, the session will be valid forever. |
| regSource | string |
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. |
Response
Upon successful generation of the access token you will receive a response in JSON format including the following parameters:
Field | Type | Description |
access_token | string | A 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 how to make an API call below. |
expires_in | number | The 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. |
For example:
HTTP/1.1 200 OK Content-Type: application/json Cache-Control: no-store { "access_token":"SlAV32hkKG", "expires_in":3600 }
Error Response
If the getToken method fails, Gigya will append the following parameters to the response:
Field | Type | Description |
error | string | The OAuth 2.0 error code. For a complete list of error codes, see the 'OAuth 2.0 Error Codes' table below. |
error_description | string | The Gigya error code and error message (separated by a dash). For example: "500001 - Server error". For the complete list of Gigya error codes and descriptions, please refer to the Gigya Error Codes table. |
state | string | The state string passed by your application as parameter to the login end-point. (See Login's table of Parameters above). |
OAuth 2.0 Error Codes
Error Code | Description |
invalid_request | The request is missing a required parameter or includes an unknown parameter or parameter value or includes repeated parameter or includes multiple credentials or utilizes more than one mechanism for authenticating the client or is otherwise malformed. |
invalid_client | The client identifier provided is invalid or the client failed to authenticate or the client provided multiple client credentials. |
unauthorized_client | The client is not authorized to use the access grant type provided. |
invalid_grant | The provided access grant is invalid, expired, or revoked (e.g. invalid assertion, expired authorization token, bad end-user basic credentials, or mismatching authorization code and redirection URI). |
unsupported_grant_type | The access grant included, its type or another attribute, is not supported by the authorization server. |
Making an API Call
A Sample API Call:
The following is an example of an HTTP GET request:
https://socialize.us1.gigya.com/socialize.setStatus?status=Hello
Note: All OAuth 2.0 REST API call are made over HTTPS.
If you wish to use HTTP, you will have to sign the request and use our legacy OAuth 1.0 compliant REST API. For more information, please read this document.
The call is composed of the following elements:
The Gigya REST API URL:
"http://<namespace>.<Data_Center>/<namespace>.<apiMethod>"
- Where
<namespace>
is:accounts
- For the RaaS Accounts APIcomments
- For the Comments APIds
- For the Data Store APIfidm
- For the Identity Management APIs (SAML / OIDC)gm
- For the Loyalty (Game Mechanics) APIids
- For the Profile Management APIreports
- For the Reports APIsocialize
- For the Socialize API
- Where <Data_Center> is:
us1.gigya.com
- For the US data center.eu1
- For the European data center..gigya.com
au1
- For the Australian data center..gigya.com
ru1
- For the Russian data center..gigya.com
cn1
- For the Chinese data center..gigya-api.cn
If you are not sure of your site's data center, see Finding Your Data Center.
The method name, which in the above example, would be:
setStatus
Method parameters. In the above example:
?status=Hello
Note: all parameter values should be in UTF-8 and URL-encoded.
Passing the Access Token
As explained above the Access Token is your authorization ticket for accessing social data. The Access Token must be passed with each REST API call. There are two methods of passing the Access Token:
- Using the Authorization HTTP header (preferred method):
GET /socialize.XXX HTTP/1.1
Host: server.example.com
Authorization: OAuth PUT-YOUR-ACCESS-TOKEN-STRING-HERE Passing the access token as a request parameter named "oauth_token".
In this case, the request from the sample API call above would be:https://socialize.us1.gigya.com/socialize.setStatus?status=Hello&oauth_token=PUT-YOUR-ACCESS-TOKEN-STRING-HERE
Receiving Responses
After sending a REST request, you will receive a response, which is a JSON object.
JSON Response Example:
"socialize.removeConnectionResponse": { "statusCode": 200, "errorCode": 0, "statusReason": "OK", "callId": "72fba4d7ff1041c180f0ea38f37dd24f" }
The name of the root element in the response consists of the name of the request API method with the word "Response" appended to it, as demonstrated in the example above: (in the response for socialize.removeConnection method).
All responses include two child elements, < statusCode > and < statusReason >, which comply with the HTTP status and status reason:
- < statusCode > - This is the equivalent of the HTTP status code, such as 200, 400, 40, etc.
- < statusReason > - The equivalent of the HTTPreason code, such as "OK", "Bad Request", "Unauthorized", etc.
Some methods also return additional data as additional children of the root element. See the documentation of each method for details on the specific data it returns.
A field that does not contain data will not appear in the response.
Error Handling
If an error occurs, the response will include two additional child elements:
- < errorCode > - An application-specific error code. This value is used to distinguish between different causes for the same statusCode.
- < errorMessage > - A detailed textual error message designated for the purpose of logging during the process of debugging.
JSON Response with Error Example:
{ "socialize.setStatusResponse": { "errorMessage": "Missing required parameter", "errorDetails": "Missing required parameter: uid", "statusCode": 400, "errorCode": 400002, "statusReason": "Bad Request", "callId": "dd1fc79e451b4dbbacefaf1072e91aff" } }
The system will return HTTP status "200 OK" for all application-level errors and return the detailed error in the body of the response. Please note that some errors, such as 503, or "Server Unreachable" will still be returned on the HTTP level and should be handled accordingly.
Error Codes
For the complete list of error codes and descriptions, please refer to the Error Codes table.