REST APIs with the Gigya Authorization Method

Skip to end of metadata
Go to start of metadata

Description

This document is a guide for using Gigya's REST API with our authorization method.

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.

Prerequisites for Using REST API Methods

Please make sure you comply with the following requirements prior to making a REST API method call:

  • Making API calls requires an API key and a Secret (or userKey/secret pair) which are obtained from the Gigya Dashboard. The Secret must never be transmitted over an insecure connection (non-SSL) or passed to the client (browser/app). The API key is a required parameter in each REST API method and the Secret is used for authentication and signing requests

  • Making REST API calls that pertain to a specific user's account (e.g., accounts.setAccountInfo) or perform any action on behalf of a specific user (e.g., socialize.publishUserAction) require that user's UID (User's ID), which can be found using accounts.search

 

To learn more about our Social Login best practice integration, please refer to the Social Login Implementation guide.

 

Authorization Parameters Overview

Each REST API request must contain identification and authorization parameters.

Note: The authorization parameters are required only if you are using the REST API directly. If you are using one of Gigya's SDKs then these parameters are not required, since the SDK performs the authorization method internally.

The set of required parameters is dependent on your selected method of authorization. There are two options:

  1. If you are conforming with the OAuth 2.0 standard, you will need to Pass an Access Token. For more information, please read the Using Gigya's REST API in compliance with OAuth 2.0 guide.
  2. If you are using Gigya's authorization method, you will need to pass the parameters specified here. Or, if you are making a call over HTTPS then you may pass the apiKey/secret or userKey/secret pair parameter(s) instead of the timestamp, nonce and sig parameters. For more information, please read the Using Gigya's REST API with Gigya's authorization method guide.
     

Making an API Call

A Sample API Call

The following is an example of an HTTP GET request:

http://<namespace>.<Data_Center>/<namespace>.<apiMethod>?uid=<User ID>&apiKey=<Your API-key>&nonce=<nonce>&timestamp=<current unix-time>&sig=<signature>&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:  <apiMethod>
     
  3. Common parameters (the following section explains this subject further):

    ?UID=<User ID>&apiKey=<Your-API-key>&nonce=<nonce>&timestamp=<current unix-time>&sig=<signature>
  4. Method-specific parameters. In the above example: 

    &status=Hello 

Note: All parameter values should be character encoded in UTF-8 and then URL-encoded.

Global Common Parameters

The following parameters are required for all API calls:

  • UID - Required when making user account level API calls - The unique ID of a connected user, which this method call is associated with. This is the UID you received from Gigya after successful login of this user or via accounts.search. Note: If you are using account linking then the UID would be your site user ID. To learn more about Social Sign-On with account linking (best practice), please refer to the Sign-On Implementation guide.
  • apiKey - The site API key from the Gigya Dashboard. You can find instructions for generating an API key here.
  • timestamp - Required if not using SSL - The current GMT time when the request is made. Follows the Unix time format (i.e. the number of seconds since Jan. 1st 1970). Requests that skew more than 120 seconds from the server time will be rejected. Not required when using a secret.
  • nonce - Required if not using SSL - A cryptographic  nonce . The nonce string must be unique per API call. Not required when using a secret.
  • sig - Required if not using SSL - A signature verifying the authenticity of the request (see Signing the Request below for more details). Not required when using a secret.
  • secret - Replaces the timestamp, nonce, and sig when making requests over SSL. This can be the Partner secret or, when using an Application key, the corresponding application's secret (see below for additional information).

The following parameter is optional for REST API calls:

  • userKey - The Application key generated by Creating an Application via the Admin tab of the  Gigya Console
    Important details related to using a userKey:
    • When using a userKey you must pass the secret associated with the userKey, not the Account's secret, as another parameter.
    • When using a userKey you do not need to send a timestampnonce, or sig.
    • When using a userKey the request must be sent over HTTPS (SSL).

 

Making a Call Over HTTPS

When making the API call over HTTPS, you may pass the secret parameter. In such cases, the  timestamp nonce and  sig parameters are no longer required.

Set the secret parameter with your Gigya Secret key which can be obtained from the Dashboard page of the Gigya website.

The following is an example of an HTTPS request using the account secret as a parameter:

https://<namespace>.<Data_Center>/<namespace>.<apiMethod>?apiKey=<Your-APIKey>&UID=<User-ID>&secret=<Your-Secret-Key>&status=Hello

The following is an example of an HTTPS request using an app/user key and app/user secret:

https://<namespace>.<Data_Center>/<namespace>.<apiMethod>?apiKey=<Your-APIKey>&UID=<User-ID>&userKey=<Your-App/User-key>&secret=<Your-App/User-Secret>&status=Hello
Note: You may only pass the secret parameter over HTTPS. If you attempt to pass the secret parameter over HTTP, the method will return the following error: Secret Sent Over Http (Error code: 403006).


Signing the Request

For security reasons, Gigya requires every API call to be signed, so as to guarantee that it originated from an authorized partner and was not tampered with in transit.

Note: We use a different algorithm for signing REST API requests and for signing API calls on client applications (JavaScript). This section discusses signing REST API requests. To learn how to sign Gigya Web SDK methods please refer to the Constructing a Signature section of the Developer's Guide.

The Authentication Flow

  1. Generate a nonce and a timestamp to be used on the call.
  2. Build a "Signature Base String" and use your Gigya Account Secret key to sign it, as described in the Generating the Signature section below.
  3. When making the call - pass the nonce, the timestamp and the calculated signature as parameters to the API method (the noncetimestamp and sig parameters).
  4. Gigya verifies that the timestamp on the call is within two minutes of the current time; if this is not the case, the call will be rejected.
  5. Gigya verifies that the nonce has not been used during the last 10 minutes; otherwise, the call will be rejected.
  6. Gigya verifies the signature by performing the same calculation, using the same Secret key and comparing the result to the sig parameter.

Generating the Signature

To generate the signature, do the following:

URL encode the request
//Unencoded:
//GET&https://socialize.gigya.com/socialize.setStatus&apikey=123456789&status=My%20New%20Status&timestamp=7627732287&uid=987654321
// ^httpMethod            ^Request URL                              ^apiKey                                                     ^uid
//                                      Params must be lexicographically sorted.
 
//Encoded:
GET%26https%3A%2F%2Fsocialize.gigya.com%2Fsocialize.setStatus%26apikey%3D123456789%26status%3DMy%2520New%2520Status%26timestamp%3D7627732287%26uid%3D987654321

 

  • Apply the HMAC-SHA1 algorithm on the "Signature Base String" with your Gigya Secret key as the key parameter of the algorithm as instructed in section 9.2 of the OAuth specifications. Your Gigya Secret key is provided, in BASE64 encoding, at the bottom of the  Dashboard  section on the Gigya website. This key should be kept on the server and should never be transmitted over any public network.
  • Base64-encode the signature.

You may use one of the OAuth libraries that can be found in http://oauth.net/code to build the Base String and generate the Signature.

Implementation Examples

It is recommended to use Gigya supplied SDKs whenever possible.


Following are implementation examples in several languages.

PHP

<?php
require_once("OAuth.php");
// Signature calculation method
// The parameters for the signature calculation are:
//  1. Your secret key
//  2. The HTTP method ('GET' or 'POST')
//  3. Method API name (e.g. 'getUserInfo')
//  4. The parameters of the API method. Note that each API method has a different set of parameters.
function calcSignatureREST($dataCenter, $secretKey, $httpMethod, $apiMethod, $parameters) { 
    $req = OAuthRequest::from_request($httpMethod,'http://socialize.'. $dataCenter . '/socialize.' . $apiMethod, $parameters);
    $baseString = $req->get_signature_base_string();  
    return  base64_encode(hash_hmac('sha1', $baseString, base64_decode($secretKey), true));
}
 
// Specify a data center e.g., 'us1.gigya.com', 'eu1.gigya.com', 'au1.gigya.com', 'ru1.gigya.com', or 'cn1.gigya-api.cn'
$dataCenter = "[ENTER THE DESIRED DATA CENTER]";
$apiKey = "[ENTER YOUR API KEY HERE]";
// Your secret key (can be found at the bottom of the Site Setup page on the Gigya website)
$secretKey = "[ENTER YOUR SECRET KEY HERE]";
$timeStamp = time();
$nonce = $timeStamp . rand();
$apiMethod = "getUserInfo";
$uid = "[ENTER THE UID FOR A CONNECTED USER HERE]";
 
// The parameters for the socialize.getUserInfo API call:
$parameters = array(
    "apiKey" => $apiKey,
    "nonce" => $nonce,
    "timestamp" => $timeStamp,
    "UID" => $uid);
$signature = calcSignatureREST($dataCenter, $secretKey, 'GET', $apiMethod, $parameters);
 
//Construct the URL and include the signature
$requestURL = "http://socialize." . $dataCenter . "/socialize." . $apiMethod . "?apiKey=" . urlencode($apiKey) . "&nonce=" . $nonce .
                "&sig=" . urlencode($signature) . "&timestamp=" . $timeStamp . "&uid=" . $uid;
                
//Check to see if libcurl is installed          
if (!function_exists('curl_init')){
    die("Sending this request requires PHP to be compiled with libcurl.");
}
 
//Now send the request
$ch = curl_init($requestURL);
curl_setopt ($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
 
echo $response;
?>
 In order to make this code work in your environment, please:
  1. Copy the source code.
  2. Modify the value of the "secretKey" field in the code, to your Gigya secret key. Your secret key is provided at the bottom of the Dashboard page on Gigya's website.
  3. Note that the 4th parameter of the calcSignatureREST function is an array of the Gigya API method parameters. In this example we use the getUserInfo API method, thus the $parameters variable is initialized with the corresponding parameters. When changing the API method, change the list of parameters accordingly. Check the REST API Reference for the list of parameters for the required method call.


Receiving Responses

After sending a REST request, you will receive a response, which is a JSON object.

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.

All responses include two child elements, which comply with the HTTP status and status reason, as well as errorCode and callId:

FieldTypeDescription
statusCodeintegerThis is the equivalent of the HTTP status code, such as 200, 400, 40, etc.
statusReasonstringThe equivalent of the HTTPreason code, such as "OK", "Bad Request", "Unauthorized", etc.
errorCode  integerAn application-specific error code. This value is used to distinguish between different causes for the same statusCode. If the response was successful, this will be returned as '0', anything else denotes an error. See also errorMessage.
callIdstringThe unique ID of this API call, for debugging purposes.


Response JSON Example:

 

  {
    "statusCode": 200,
    "errorCode": 0,
    "statusReason": "OK",
    "callId": "72fba4d7ff1041c180f0ea38f37dd24f"
  }

 

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:

FieldTypeDescription
errorMessage stringA textual error message designated for the purpose of logging during the process of debugging, based on the returned errorCode.
errorDetailsstringA more detailed description of the specific error.

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.

 

Response JSON with Error Example:

 

    {
      "errorMessage": "Missing required parameter",
      "errorDetails": "Missing required parameter: uid",
      "statusCode": 400,
      "errorCode": 400002,
      "statusReason": "Bad Request",
      "callId": "dd1fc79e451b4dbbacefaf1072e91aff"
    }

 

Error Codes

For the complete list of error codes and descriptions, please refer to the Error Codes table.