Using the REST API

Skip to end of metadata
Go to start of metadata

Introduction

Gigya's REST API is the core of Gigya's service. On top of the REST API, Gigya offers a set of Server Side SDKs that wrap around the API. The Server Side SDKs make it simple to integrate Gigya's service in server applications of various development environments.

Check out our Server Side 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.

 

Requests

Gigya's server-to-server API uses a REST-like interface. This means that the API method calls are made over the internet by sending HTTP GET or POST requests to the Gigya REST API server and the response is returned as XML/JSON. Nearly every software development environment provides methods for communicating over HTTP with a REST server.

Gigya's REST API may be applied in compliance with the OAuth 2.0 standard or with our proprietary authorization method. Please follow one of the following guides, to integrate Gigya's REST API calls, using your preferred authorization method:

Application and User Keys

Using the Gigya API with a User Key

If you are not the main site administrator, you may not have access to the Partner Secret Key. Instead, you can call the GIgya API using your user key and user secret. You still need to pass the API Key of the target site. Note that calls performed this way are subject to the user key's permissions and are logged for auditing purposes.

When you pass a request across HTTPS, include the site's API Key and your personal User Key and Secret. For example:

 

https://...?apiKey=[SITE_API_KEY]&userKey=[USER_KEY]&secret=[USER_SECRET]

 

For more information about user keys, including instructions for finding your user key in the Gigya Console, see Using the User Key.

Creating A User Key

You can make REST Requests using a userKey and secret. This is useful for delegating access to Gigya APIs without revealing your account's secret to multiple users. You can create multiple Applications, and give groups of users access to these various applications with each application having only the permissions that you define in it's settings. Each application has a userKey and secret that can be used when making REST calls to Gigya API Endpoints.

Another benefit of using a userKey and secret is that the user does not have to construct or check signatures, however, this means that all requests must be conducted over HTTPS.

To manage your Gigya Applications:

  1. Login to your Gigya Console.
  2. Navigate to the Admin tab.
  3. Select Manage Applications.
  4. Once on the Applications page, press Create New Application and follow the on-screen prompts.



  5.  Once the app is created you can view the Apps userKey and secret by clicking the Edit icon, which will take you to the apps Edit Application page.



  6.  You can disseminate this userKey and secret to users whom you want to attain the privileges associated with this app. Users will use this userKey and replace the secret parameter in the request with the secret associated to this key.
  7. If at any time you want to revoke access for users using this Application, simply delete it from your account and all future attempts to use this userKey and secret will fail.

 

curl Code Example

curl https://accounts.us1.gigya.com/accounts.search 
 --data-urlencode "apiKey=3_mKxxxxXXXXXXXXxxxxxxxxXXXXxxXxxxxxxxxxxxxxxxxxxXXXXXXXXXXXXxxxxx" 
 --data-urlencode "userKey=AJxXXxXxxX2X" 
 --data-urlencode "secret=X73xXXXXXxxxxXXXxxxXXXx656767Xxx" 
 --data-urlencode "format=json" 
 --data-urlencode "query=select UID, identities.provider, identities.providerUID from accounts limit 10"

In the above example, the secret is the secret associated with the userKey, not the account secret located in the Gigya Dashboard.

 

 

The REST API Reference provides specification to the various REST API methods supported by Gigya.

Important: When using the REST API, all post data must be URL Encoded prior to being sent to the Gigya server, whether in the query or body of the request. If sending in the body, all parameters must be of content-type "www-form-urlencoded".

Handling Unknown Parameters

When calling an API, parameters that are not found in the method signature are ignored and discarded by default, allowing the request to be processed. In such a case, any parameters which have been ignored appear in the response, as follows:

 

{
  "statusCode": 200,
  "errorCode": 0,
  "statusReason": "OK",
  "callId": "b0cce660845e4e40bf3d4663953564f3",
  "time": "2015-01-04T08:48:28.537Z",
  "ignoredParams": [
    {
      "paramName": "ignoreMe",
      "warningCode": 403007,
      "message": "This parameter was not recognized as valid for this API method with your security credentials nor was it recognized as a standard Gigya control parameter."
    }
  ]
}

To force an API call to fail with an error response when unknown parameters are encountered, pass the 'checkParams' control parameter with a value of 'true'.

This parameter can be passed for all API calls, and if its value is 'true', the server will return an error for any undefined parameter that was passed in the request (on a first find policy). See below the response from the same request as the example above, however, this time with checkParams=true:
{
  "errorMessage": "Permission denied",
  "errorDetails": "These parameters were not recognized as valid for this API method with your security credentials nor were they recognized as standard Gigya control parameters: ignoreMe",
  "statusCode": 403,
  "errorCode": 403007,
  "statusReason": "Forbidden",
  "callId": "2b5401d43d664fc1846b02d2e26733f3",
  "time": "2015-01-04T09:01:57.746Z"
}