This document is a guide for using Gigya's REST API with our authorization method.
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.
The set of required parameters is dependent on your selected method of authorization. There are two options:
- 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.
- 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:
The call is composed of the following elements:
The Gigya REST API URL:
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- For the European data center.
au1- For the Australian data center.
ru1- For the Russian data center.
cn1- For the Chinese data center.
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: <apiMethod>
Common parameters (the following section explains this subject further):
Method-specific parameters. In the above example:
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 timestamp, nonce, 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:
The following is an example of an HTTPS request using an app/user key and app/user secret:
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.
The Authentication Flow
- Generate a nonce and a timestamp to be used on the call.
- Build a "Signature Base String" and use your Gigya Account Secret key to sign it, as described in the Generating the Signature section below.
- When making the call - pass the nonce, the timestamp and the calculated signature as parameters to the API method (the nonce, timestamp and sig parameters).
- 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.
- Gigya verifies that the nonce has not been used during the last 10 minutes; otherwise, the call will be rejected.
- 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:
- 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.
It is recommended to use Gigya supplied SDKs whenever possible.
Following are implementation examples in several languages.
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:
|statusCode||integer||This is the equivalent of the HTTP status code, such as 200, 400, 40, etc.|
|statusReason||string||The equivalent of the HTTPreason code, such as "OK", "Bad Request", "Unauthorized", etc.|
|errorCode||integer||An 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.|
|callId||string||The unique ID of this API call, for debugging purposes.|
Response JSON Example:
A field that does not contain data will not appear in the response.
If an error occurs, the response will include two additional child elements:
|errorMessage||string||A textual error message designated for the purpose of logging during the process of debugging, based on the returned errorCode.|
|errorDetails||string||A 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:
For the complete list of error codes and descriptions, please refer to the Error Codes table.