Was this article helpful?

OAuth 2.0 Compliant REST API

Last modified 10:53, 15 Sep 2014

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

REST-API_OAuth2_diagram1.gif
 


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.
 

REST-API_OAuth2_diagram3.gif

 

Implementation steps:

          Your Client Application:

  1. Login the user via the Gigya service, using our JavaScript API method calls: socialize.login or socialize.notifyLogin. You may also use our ready made Login Plugin.
  2. In the Login response you will receive the User object.
     
    Note:
    1. To learn how to implement client side login using our JavaScript API, please refer to the Social Login page in the Developer's Guide.
    2. An alternative implementation to steps 1&2 is to use the Login end-point to login 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:
     
  4. Obtain the access_token using the getToken end-point. Pass the grant_type=“none” parameter. The getToken must be called over HTTPS. Read more in the section below.
  5. Receive the getToken method response. The response will contain the access_token. Note: in this use case the token is not related to a specific user.
  6. 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.
  7. Receive REST API method response.

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.

Note: Gigya supports this flow to conform with the OAuth 2.0 standard. Nevertheless, we encourage you to prefer Flow 2 over this flow.

REST-API_OAuth2_diagram2.gif


Implementation steps:

          Your Client Application:

  1. Login the user via the Gigya service, using our JavaScript API: the Login Plugin or the socialize.login API method. 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.

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

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

 

The Login End-Point

Gigya provides an end point for user login using his social network / webmail account. This login end-point requires user interaction. To login the user, 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 and MySpace, users will also be asked to give the site permission to access their personal data. When the login process completes, Gigya server will redirect the user to a URL by your choice.
The login operation is currently supported by the following providers: Facebook, Twitter, Yahoo, Microsoft Messenger, Google, Google+, LinkedIn, AOL, FourSquare, Instagram, Renren, Tencent QQ, Sina Weibo, Kaixin, Vkontakte, WordPress, Blogger, Typepad, Paypal, Amazon, liveJournal, VeriSign, OpenID, Netlog, Signon, Orange France, mixi, Yahoo JAPAN, Odnoklassniki, Spiceworks, Livedoor, Skyrock, VZnet, Xing.

 

The Login End-Point URL

http://socialize.gigya.com/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("http://socialize.gigya.com/socialize.login?client_id=2_Y82PzwJ_chSFImHXaIDJClnLyJzmk-VFOavSsaNTzl6m901s_NNxRAS0xJ3bd3_N&" + 
                             "redirect_uri=http://wikifiles.gigya.com/Socialize/REST-PostLoginPage.htm&x_provider=facebook&response_type=token");
    }
</script>
<form>
<input type=button value="Login to Facebook" onclick="open_win()">
</form>

 

Parameters

Required Name Type Description
Required x_provider string The provider which will be used for authenticating the user. The following values are currently supported for use with this parameter:
facebook, twitter, yahoo, messenger, googleplus, linkedin, aol, foursquare, instagramrenren, qq, sina, kaixin, vkontakte, blogger, wordpress, typepad, paypal, amazon, livejournal, verisign, openid, netlog, signon, orangefrance, mixi, yahoojapan, odnoklassnikispiceworks, livedoor, skyrock, vznet, xing.
  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.
Optional 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  Boolean The default value of this parameter is false. Setting this parameter to true, indicates that the account is temporary and is only accessible with the associated access token. This means that it is not possible to access the same account, and get the same Gigya UID, again by using login. 
  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:

  1. Using HTTP Basic Authorization header (this is the preferred method) -
    The Authorization value should be constructed as follows: BASE64(<YOUR-API-KEY> + ":" + <YOUR-SECRET-KEY>).
    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
  2. Using query parameters -

    client_id - The Gigya API key

    client_secret - The Gigya Secret Key
     

The getToken Request URL

https://socialize.gigya.com/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.

Parameters for grant_type=authorization_code:

Required Name Type Description
Required 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).
Optional 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:

Required Name Type Description
Required grant_type  string "none"
Optional 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. 
  x_userInfo JSON string This parameter is relevant only if the x_siteUID parameter (see above) is specified.
This parameter allows you to provide Gigya with site's user profile data. This will ensure consistent user experience. Gigya will use this information, for example, in Plugins that show user info, such as the Chat and the Comments Plugins.
The object may include the following fields: nickname, photoURL, thumbnailURL, firstName, lastName, gender, age, email.
For example:
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.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:

  1. The Gigya REST API URL: 
    https://socialize.gigya.com/
     
  2. The method name, which, in the above example, would be: 
    socialize.setStatus
     
  3. 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 method of passing the Access Token:

1. Using the Authorization HTTP header (This is the 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.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 by default an XML string.

Response XML Example:

<?xml version="1.0" encoding="utf-8" ?>
<socialize.disconnectResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xsi:schemaLocation="urn:com:gigya:api http://socialize.gigya.com/schema/1.0.xsd" xmlns="urn:com:gigya:api">
    <statusCode>200</statusCode>
    <statusReason>OK</statusReason>
</socialize.disconnectResponse>

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: <socialize.disconnectResponse> (in the response for socialize.disconnect 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.

Note: 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.

Response XML with Error Example:

<?xml version="1.0" encoding="UTF-8" ?>
<socialize.setStatusResponse xmlns="urn:com:gigya:api" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
            xsi:schemaLocation="urn:com:gigya:api http://api.gigya.com/schema/1.0.xsd">
    <statusCode>500</statusCode>
    <statusReason>Internal Server Error</statusReason>
    <errorCode>500024</errorCode>
    <errorMessage>No valid session</errorMessage>
</socialize.setStatusResponse>

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.

Was this article helpful?
Pages that link here
Page statistics
45232 view(s) and 14 edit(s)
Social share
Share this page?

Tags

This page has no custom tags.

Comments

You must to post a comment.

Attachments