Gigya Job Openings

socialize.getToken REST

Skip to end of metadata
Go to start of metadata

Any reference to OpenID or OpenID Provider on this page is referring specifically to the OpenID OAuth 2.0 Protocol. For information pertaining to OpenID Connect, please see our OpenID Connect documentation.

Description

This API retrieves an access token, which is required as part of the OAuth 2.0 protocol. Read more in The OAuth 2.0 protocol.

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 Dashboard section on Gigya's website. When using the Gigya REST API directly, you can also use a userKey (application key) and secret in lieu of the partner's secret. A Secret Key must be kept secret and never transmitted to an untrusted client or over insecure networks. There are three 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("<client_id>" + ":" + "<client_secret>")

    (You can not use an application or user key with this method)
    For example:

    POST /token HTTPS/1.1
    Host: server.example.com
    Authorization: Basic PUT-YOUR-KEYS-STRING-HERE
    Content-Type: application/x-www-form-urlencoded
  2. Using grant_type of authorization code with query parameters and partner secret -
    client_id - The Gigya API key
    client_secret - The Gigya Secret Key

  3. Using grant_type of none or client_credentials with query parameters and user/application key and secret - This method may also use only the client_id and client_secret (partner secret) like option 2, above.
    client_id - The Gigya API key
    userKey - The user or application key
    secret - The user or application key's secret


Request URL

https ://socialize.gigya.com/socialize.getToken

Parameters

The behavior of the getToken method is determined by the grant_type parameter. The set of parameters which the method receives depends on the grant type.

Parameters for grant_type=authorization_code:

RequiredNameTypeDescription
grant_type stringauthorization_code
codestring

The verification code received from the login response (Read more in Use case 3 flow).

  • If the code parameter is not passed, an error Missing_required_parameter (errorCode 400002) is returned.
  • If an invalid code parameter is passed, an error Invalid_parameter_value (errorCode 400006) is returned.
redirect_uristringThis 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).
regSourcestring

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=client_credentials:
(You may use a user or application key and corresponding secret only using this method or 'none', below)

RequiredNameTypeDescription
grant_type stringclient_credentials
x_siteUIDstring

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. Note that any providerSessions parameter will be ignored and if a user is not yet logged in, this will not automatically log the user in.

x_userInfoJSON 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_sessionExpirationintegerThe 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.
regSourcestring

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:
(You may use a user or application key and corresponding secret only using this method or 'client_credentials', above)

RequiredNameTypeDescription
grant_type stringnone
x_siteUIDstring

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. Note that any providerSessions parameter will be ignored and if a user is not yet logged in, this will not automatically log the user in.

x_userInfoJSON 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_sessionExpirationintegerThe 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.
regSourcestring

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 Data

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

FieldTypeDescription
access_token stringA 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 more in making an API call. The token is a privileged token that has almost the same permission as using an API key with the secret, and for this reason should only be passed down to the end user when necessary.
expires_innumberThe duration in seconds of the access token's lifetime.
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:

FieldTypeDescription
errorstringThe OAuth 2.0 error code. For a complete list of error codes, see the Error Codes table below.
error_descriptionstringThe Gigya error code and error message (separated by a dash). For example: "500001 - Server error".
statestringThe state string passed by your application as parameter to the login end-point. (See Login's table of Parameters).

Error Codes

Error CodeDescription
invalid_requestThe 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_clientThe client identifier provided is invalid or the client failed to authenticate or the client provided multiple client credentials.
unauthorized_clientThe client is not authorized to use the access grant type provided.
invalid_grantThe 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_typeThe access grant included, its type or another attribute, is not supported by the authorization server.
Missing_required_parameterA required parameter was missing from the request.
Invalid_parameter_valueA parameter that was passed has a value that is incorrect or not supported.