OAuth 2.0 Compliant REST API

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.

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 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

1. 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.
2. In the Login response you will receive the access_token. This token is your authorization ticket for accessing the current user's social profile.
3. Pass the access_token with each REST API method call, related with the current user. Read how to make an API call below.
4. Receive REST API method response.

Use Case 2 - Direct Server to Server Flow

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:

1. 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.

2. In the Login response you will receive the User object.

   Notes:

   1. To learn how to implement client side login using our Web SDK, see Social Login.
   2. 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.

3. Pass the User object to your server application.

Your Server Application:

1. 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.
2. 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.
3. 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.
4. 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

1. 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.
2. Receive the getToken method response. The response will contain the access_token.

Your Client Application:

1. 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);
        }
   

2. Gigya services will now be loaded with the user already logged in.

Use Case 3 - Web Server Flow

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:

1. 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.
2. In the onLogin event data (or in the socialize.login API method response) you will receive the authCode.
3. 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:

1. 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.
2. 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.
3. Pass the access_token with each REST API method call, related to the user. Read how to make an API call below.
4. 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

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

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:

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:

Error Response

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

OAuth 2.0 Error Codes

Getting an Access Token

This method retrieves an access token.

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:

1. 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

1. 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

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.

x_siteUID=12345&userInfo;={firstName:"David", gender:"male", age:30}

Response

Upon successful generation of the access token you will receive a response in JSON format including the following parameters:

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:

OAuth 2.0 Error Codes

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

The call is composed of the following elements:

1. The Gigya REST API URL: 
   "http://<namespace>.<Data_Center>/<namespace>.<apiMethod>"

   • Where <namespace> is:

     • accounts - For the RaaS Accounts API
     • comments - For the Comments API
     • ds - For the Data Store API
     • fidm - For the Identity Management APIs (SAML / OIDC)
     • gm - For the Loyalty (Game Mechanics) API
     • ids - For the Profile Management API
     • reports - For the Reports API
     • socialize - For the Socialize API

   • 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.

2. The method name, which in the above example, would be: 
   setStatus

3. Method parameters. In the above example: 
   ?status=Hello

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:

1. 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
   
   

2. 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"
  }

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.

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.