Skip to main content
Gainsight Inc.

Generate REST API Key

Gainsight NXT

 

IMPORTANT: Gainsight is upgrading Connectors 2.0 with Horizon Experience. This article applies to tenants which have been upgraded to the Horizon Experience for Connectors 2.0. If you are using Connectors 2.0 with the previous version, you can find the documentation here.

This article explains how Admins can generate the Gainsight API Access and M2M OAuth key.

Overview

Gainsight uses the API Access key and M2M OAuth to authenticate REST API requests securely. Admins can generate the API keys that developers use in the request headers to access Gainsight services.

Limitations:

  • Only one Access key can be created per organization.
  • A maximum of 15 M2M OAuth keys can be created per organization.

Gainsight authenticates the REST API requests by verifying the key. If authentication succeeds, developers gain access to the Gainsight platform via REST APIs.

You can reset the existing access keys anytime. However, ensure the new key is updated in all future API request headers.

Generate Access Key

To interact with Gainsight APIs, developers need an Access Key for authentication. To generate the Access key:

  1. Navigate to the Administration > Connectors 2.0.
  2. Click Create Connection. The Create Connection dialog box appears.
  3. From the Connector dropdown list, select Gainsight API.
  4. In the Name of the connection field, enter the name of the connection.
  5. In the Authentication Type, select the Access_Key.
  6. Click Generate Access Key.

A new access key is generated which you can copy and use for authentication in all REST API requests to Gainsight.

Create Connection dialog for Gainsight API, with Access Key selected as the authorization type and an option to generate the key.

Edit Gainsight API Connection

Admins can edit the Gainsight API Connection to reset the existing API access key.

To reset the existing API access key:

  1. Click the three vertical dots of the created Connection and select Edit Connection. The Edit Connection dialog appears.
  2. Click Re-Generate Access Key to generate a new access key.
  3. Click Re-Generate on the confirmation message.

A new access key is generated, which you can copy and use for authentication in all future REST API requests to Gainsight.

Edit connection settings in Gainsight API with access key or OAuth options.

Note: The new access key should be replaced in the headers of all future API requests. If it is not replaced, all future API requests to the specific Gainsight org will fail.

Generate M2M OAuth Key

To generate the M2M OAuth key:

  1. Navigate to Administration > Connectors 2.0.
  2. Click Create Connection. The Create Connection dialog appears.
  3. From the Connector dropdown list, select Gainsight API.
  4. In the Name of the connection field, enter the name of the connection.
  5. In the Authentication Type, select the OAuth.
  6. Click Generate OAuth Credentials.

New OAuth API Key and OAuth API Secret keys are generated, which you can copy and use for authentication in all of the REST API requests to Gainsight.

Note:

  • M2M OAuth can be created and managed only by super admins.
  • M2M OAuth cannot be used for Event APIs.
  • Two different M2M connections cannot have the same name for a single connection.

Create Connection dialog for Gainsight API with OAuth selected as the authorization type and fields for API key and secret

Admins can also generate and validate tokens for M2M authentication. For more information, refer to the section below.

Generate and Validate Tokens

API Scopes:

  • GET APIs: Available for both super admins and non-super admins.
  • Create, Update, and Patch APIs: Available only to super admins.

Headers

Key Value
Authorization Basic base64(client_id:client_secret)

Note: Client ID and Client Secret can be obtained from the above section Generate M2M OAuth Key.

Throttling Limits

The following are the overall recommended API limits in Gainsight.

Synchronous API Calls: 100 API calls per min / 50,000 API calls per day.

Get Access Token API

The Get Access Token API is used to generate an access token that is required to authenticate 

and authorize API requests.  For more information, refer to the link provided here.

Method

POST

Endpoint URL

https://<<tenant-url>>/v1/users/m2m/oauth/token

Sample Success Response

{
      "access_token": "<<access_token value>>",
      "token_type": "Bearer",
      "expires_in": 86400
  } 

Active State of a Token API

The Active state of a Token API is used to determine the active state of a token and meta-information about it, such as its expiry information. For more information, refer to the link provided here.

Headers

Key Values
Authorization Basic base64(client_id:client_secret)
Content-Type application/json

Method

POST

Endpoint URL

https://<<tenant-url>>/v1/users/m2m/oauth/token/introspect

Sample Request Body

{
      "access_token": "XXXXXXXXX"
} 

Sample Success Response

{
  "active": true,
  "client_id": "XXXXXX",
  "token_type": "Bearer",
  "exp": 1729123263000
} 

Sample Failure Response

{
"requestId": "170a3a0b-bfe4-4337-a961-a24196925d8b",
"error": "unauthorized"
} 
  • Was this article helpful?