Skip to main content
Gainsight Inc.

OAuth for Gainsight APIs

  1. Last updated
  2. Save as PDF 
Gainsight NXT

 

This article explains to admins about the Open Authorization (OAuth) for Gainsight APIs.

Overview

Gainsight offers REST APIs to integrate your applications or services with the Gainsight platform. Using these APIs, you can insert or update data into the Gainsight applications from external systems. This feature helps integrate with Gainsight with more flexibility. Gainsight has the following two methods to control access to the APIs:

  • Access Key

  • OAuth

This article provides information on the OAuth process only. For more information about Access Key, refer to the Generate API Access Key article.

For more information about OAuth 2.0, refer to the OAuth 2.0 article.

Prerequisites

  • Your org must have Connectors 2.0 (Horizon Experience) to use the OAuth atuhentication for APIs.

  • Callback URL: This is a URL where you receive the Authorization Code post authorization.

Configure OAuth for accessing Gainsight APIs

The following are the major steps to configure OAuth for accessing Gainsight APIs:

  1. Create Application

  2. Obtain Authorization Code

  3. Generate Access Token

Create Application

In the User Management page, admins can create an application to get Client ID and Client Secret. 

To create an application:

  1. Navigate to the Administration > User Management > Authentication tab > OAuth Applications tab.

  2. Click Add Application.

  3. In the Name field, enter a unique name of the application.

  4. From the Scope dropdown list, select Read or Read/Write.
    Note: The Scope selected within the application applies to all Gainsight APIs. 

  5. In the Callback URLs field, enter the URL for the callback.

  6. (Optional) Click Add another URL to add another URL for callback.

  7. Click Add Application. The Client ID and Client Secret are generated, which can be copied from the list page.

Screenshot 2024-06-29 at 11.05.18 PM.png

IMPORTANT: 

  • Admins can create only one application in Gainsight. The same Client ID can be used to generate multiple Authorization Codes for different Scopes passed in the browser.These authorization codes can be used for generating Access Tokens from different external agents (browser or applications). For more information about Authorization Code and Access Token, refer to the Obtain Authorization Code and Generate Access Token sections.

  • While creating an application, Permissions (of authorizing a user) and Scope (selected in the application) play an important role in defining access type for the external application, which are accessing the Gainsight APIs. The following are the two scenarios where access is provided based on the selected scopes and user’s permissions:

    • If the authorizing user has fewer permissions than the scope provided in the application or in the browser, then the level of access for the external application will be as per the user’s permissions.

      For example, If the user has only Read Permission, an application getting authorized by the same user will not be able to Write into any object accessed via the APIs.

    • If the Scope provided in the application or in the browser is lesser than the Permissions given to the user, then the level of access for the external application will be as per the Scope provided in the application or the browser.

  • After generation of the Authorization Code, if the Scope of an application is changed, the users must regenerate the Authorization Code for the new Scopes.

  • After the Access Token has been generated, if the authorizing user’s permissions change, they will have to re-authorize to generate a new Access Token and Refresh Token as the existing tokens will have access to the data according to the user’s previous permissions.

Obtain Authorization Code

After creating an application, you need to generate an Authorization code. The Authorization code is used to generate Access and Refresh Tokens.

Note: Authorization code can be generated for each type of Scope (Read or Read/Write).

To obtain the Authorization Code:

  1. In a new browser tab, enter the following URL and replace the Application URL, Client ID,  Callback URL, and Scope.

URL format: <Insert application URL>/v1/authorize?clientId=<Insert client id>&redirectUri=<Insert Callback URL>&scopes=<scope>

Sample URL: https://xyzcompany.gainsightcloud.com/v1/authorize?clientId=yGCCltz2ZZuqhUqfB2DgUPInBaFlq7uR&redirectUri=https://oauthtest..com&scopes=read_write

IMPORTANT: 

  • redirectUri and Callback URL provided while creating the application must be the same.
  • Only two scopes can be provided, read or read_write.

  1. Press Enter on your keyboard. The login page of Gainsight is displayed.

  2. Enter the Username and Password.

    Note: The application can access data based on the permissions of the user who authorized the application.

  3. Click Log IN. This redirects you to the Callback URL provided in the application. You can find the Authorization Code in the URL. 

Generate Access Token

You can generate the Access Token by entering the following URL in the POST method.

URL: <application URL>/v1/users/oauth/token

Notes:

  • User Permissions restrict the data that can be accessed by the APIs when called using the Access Tokens.
  • Gainsight follows the Authorization Code flow of the OAuth authentication, that is, an authorization code is required to generate the Access Token.

Replace the Client Secret and Authorization code in the request body.

{

    "clientId": "Insert Client ID",

    "clientSecret": "Insert Client Secret",

   "grantType":"authorization_code",

   "redirectUri" : "Insert URL",

   "code" :"Insert Code"

}

You will get a JSON response back containing the Access Token (validity 3600 seconds) and Refresh Token. The following is a sample JSON response:

{

    "result": true,

    "errorCode": null,

    "errorDesc": null,

    "requestId": "wquoiueoiasd",

    "data": {

        "accessToken": "ukjds80asdsvdfvsdvdsvsdvsdvdvskjlklk112nkl",

        "refreshToken": "dassadaadjlsadjlsaddadvdsddsdvsdvdvdssdvd",

        "TokenType": "Bearer",

        "expiresIn": 3600

    },

    "message": null

}

You can use this Access Token in the Gainsight APIs and Bulk API job’s cURL Command. For more information about how to generate the cURL command, refer to the Gainsight Bulk API and API and Developer Docs articles.

Refresh Token

After an Access Token expires, you can get a new Access Token by using the Refresh Token generated with the Access Token. The following script shows the sample request body to refresh the Access Token:

Note: Everytime you generate an Access Token a new Refresh Token is generated along with it. The newly generated Refresh Token is valid for an hour, after which a new Refresh Token is generated.

{

  "clientId": "Insert Client ID",

       "clientSecret": "Insert Client Secret",

   "grantType":"refresh_Token",

        "refreshToken": "Insert Refresh Token"

}

 Note:  The refresh token, once generated has life time of 1 Hr, within which it should be used to generate the access token. 

If not used within 1 hr, user need to reauthorize to generate new refresh token.  If used within 1 hr, Gainsight gets another refresh token along with access token. Immediately old refresh token gets revoked. So, 2 refresh tokens cannot be available to use any time.

Revoke Authorization

Admins can revoke the authorization of an application to restrict the access to Gainsight data, if required.

To revoke authorizations of an application:

  1. Navigate to the Administration > User Management > Authentication > OAuth Applications.

  2. Click the three vertical dots menu and select View/Edit. The OAuth Application details page is displayed.

  3. Click Authorizations.

  4. Click the three vertical dots menu and select Revoke Authorization. A confirmation dialog is displayed.

  5. Click Confirm.

Note: When a user authorization is revoked, the Refresh Token becomes invalid.

Screenshot 2024-06-29 at 11.07.25 PM.png

Revoke Refresh Token

Admins can revoke the Refresh Token by calling the APIs. The following are the required details for revoking the Refresh Token:

Method POST
URL https://<application URL>/v1/users/oauth/revoke
Request Headers Content-type: application/json

Request Body

{
    "clientId": <Insert clientId>,
    "clientSecret": <Insert clientSecret>,
    "refreshToken": <Insert refreshToken>
}

Refresh Token Status

Admins can view the status of the Refresh Token in the Authorization tab. The newly generated Refresh Token is valid for an hour, after which a new Refresh Token is generated. The following are the statuses:

  • Active: Indicates that the Refresh Token is active and can be used to generate new Access tokens.

  • Expired: Indicates that the Refresh Token is expired and cannot be used to generate new access tokens. Users have to re-authorize to generate a new Refresh Token, refer to Obtain Authorization Code section in this article.

  • Revoked: Indicates that the Refresh Token is revoked by the user. Users can re-authorize to generate a new Refresh Token.

  • Invalid: Indicates that the Refresh Token has become invalid due to the deactivation of the user.

Delete an Application

Admins can delete an application to remove the authorization of the application. When an application is deleted, access to Gainsight data of the external application is automatically restricted.

To delete an application:

  1. Navigate to the Administration > User Management > Authentication > OAuth Applications.

  2. Click the three vertical dots menu and select Delete. A confirmation dialog is displayed.

  3. Click Yes.

Note: If the application is deleted, all codes or tokens will be invalid.

Deactivate Application

When an application is deactivated, Access Token and Refresh Token generated for the application are temporarily blocked until the application is activated again.

To deactivate an application:

  1. Navigate to the Administration > User Management > Authentication > OAuth Applications.

  2. Turn OFF the Status toggle switch to deactivate the application.

OAuth with Gainsight APIs

You can authorize the Gainsight APIs by using OAuth, when accessing Gainsight data from the external applications. The following are the details required for validation of the API call:

Method Details

HTTP Method PUT
Content Type application/json
Response Format JSON
Requires Authentication Yes
Header

Accesskey: Pass the API Access key you received from Gainsight in the header “Accesskey”

Or

Authorization: Pass the “Bearer <Access Token>” in the header

Required Parameters

Required Parameters How To Use Description
API Key Passed through the Request Header Pass the API Access key you received from Gainsight in the header “Accesskey”. 
Authorization Passed through the Request Header Pass the “Bearer <Access Token>” in the header.
New Record or Update Record JSON Passed through the Request Body This is the JSON that represents a new record that you create in the Person object or update an existing record. A sample JSON is shown in the below section Request Body.
Key Passed through the Request Body Email is the only field that helps to identify a record in the Person object. Passing this field through API request body is mandatory. Using this field, remaining fields in the Person object are updated or a new record is created.

Additional Resources

For more information on the Gainsight APIs, refer to the following articles: