Create an app for Gong

This article covers how to create an app for Gong which supports data residency regulations.

Step 1: Initial setup in Gong & get OAuth keys

In this step, you'll provide information needed to create an OAuth client, which can then be used to access the Gong API on behalf of mutual customers.

In your company's Settings page, click API and click the Integrations tab.
Click Create Integration.
In the Integration details area, enter your integration name and a description.
In the App logo area, upload 2 different-sized logos:
- The small logo is used in the Gong app management page
- The large logo is used in the OAuth connection approval screen
In the Required authorization scopes area, select the scopes that your app needs.

You can check our API documentation to see which APIs use which scopes.
Add the links requested for your app:
- Redirect URIs
- Link to your integration's service and privacy terms
- Link to your license agreement
- Link to your integration's help article
- Link to page in your integration where authorization process begins
- Emails of contacts in your organization
Click Save.

A new row appears in the table of apps, containing the Client ID and the Client Secret. In the table, you can also see the app status and edit app details.

Step 2: Set up OAuth access

Using the keys you got in the last step, set up OAuth so that your app can access Gong's API on behalf of our mutual customers.

This setup flow follows the standard OAuth procedures as per RFC 6749, and explains the details of the protocol.

Step 2.1: Use the authorization code flow

As per the OAuth standard, set up a UI component that will send the user (who must be a technical administrator in Gong) to the Authorization page in Gong at the following URL.

Your request URL should be similar to this:

https://app.gong.io/oauth2/authorize?
client_id=038HLrv1cef0h7&response_type=code&scope=api:calls
:create%20api:calls:read:basic&redirect_uri=https://example
.com/oauth_cb&state=296bc9a0-a2a2-4a57

The endpoint receives the following parameters:

client_id matches the Client ID of your Gong OAuth application, that was provided by Gong in the step 1.
response_type is code, indicating that we're using the authorization code grant type.
Use scope to specify the access scopes you need in your app. The value of the scope parameter is expressed as a space-delimited list of strings. These are the scopes you requested in step 1.
redirect_uri is the callback endpoint where the user-agent (browser) will be redirected along with the access code. This must match one of the redirect URIs you specified when creating your application in Step 1.
state is a random arbitrary alphanumeric string that the authorization server will reproduce when redirecting the user-agent back to the client. This is used to help prevent cross-site request forgery.

For more information on these parameters, refer to the OAuth 2.0 Specification.

In response to the authorization URL above, if the user does not have an active Gong sign-in session, it will open the Gong sign-in page and the user will be signed in. An authorization page will appear requesting approval of the scopes.

Once the user approves, they will be redirected to the redirect_uri endpoint specified, along with a code and the state, as shown here:

https://example.com/oauth_cb?code=
eyJlbmMiOiJBSlV2R0NNIiwiYWxnIjoiZGlyIn0.RSJretizGL2N8625.5
GrNjj9jBKSMzaRYsktK3Q9CFa9vOqSVMRwbewEJXXPvexMSA0R8Q
PLeeQjeda1hHbPIABFAS82sVRMPQ.GF6t2dK-PvqbLs32iWc5pg
&state=296bc9a0-a2a2-4a57

The code is valid for 10 minutes, during which it can be exchanged for an access token as explained below.

Step 2.2: Exchange the code for an access token

To get an access token, pass the access code to the /generate-customer-token endpoint. Use HTTP Basic Authorization when sending the POST request as shown below:

Authorization: Basic <token>

To create the basic token, combine the client_id and the client_secret you retrieved with a colon (:), and then encode in Base64 as shown here:

Base64(<client_id>:<client_secret>)

Following is the URL for the HTTP POST request:

https://app.gong.io/oauth2/generate-customer-token?
grant_type=authorization_code&code=eyJlbmMiOiJBMjU2R0NNIiw
YWxnIjoiZGlyIn0..S_6dW2iO3QJj_D0s.Sa7P1N
y1XYsIgNDtAffPG3kh0ovf0_QPTXitYpUdRztXWGmkZrUQHFVbAs41ZKuB
wSIJSfyvJdKnIruZ
1WN_i.hajm9Bxv7JInrX503iGeZw&client_id=rekgfz28j&redirect_
ri=https://example.com/oauth_cb&validity_duration=600

The generate-customer-token endpoint receives the following parameters:

code: the access code you retrieved in Step 2.1.
client_id: the Client ID of the Gong OAuth application that you created.
redirect_uri: the callback location where the user-agent is directed along with the code. This must match the redirect_uri that was specified in the token request in Step 2.1.
validity_duration: (optional) defines the number of seconds the token is valid for. By default, the token is valid for 1 day. Include this parameter if you want to change the default amount of time the token is valid for.

The generate-customer-token response is as follows:

{
"access_token": "eyJhbG[...]9pDQ",
"refresh_token": "eyJhbF[...]5lSA",
"expires_in": 525600,
"token_type": "Bearer",
"scope": "api:calls:create api:calls:read:basic”
<!-- this parameter is only returned by the generate-customer-token as part of data residency support -->
"api_base_url_for_customer": "https://company-17.api.gong.io"
}

This returns the access token which by default is valid for 1 day. The token should be used in the Bearer token authentication in the Gong Public API, and a refresh token for the future (see step 2.3).

Requests using this authentication token should be directed to the URI specified in the api_base_url_for_customer parameter. The api_base_url_for_customer is different for each customer and should be saved as part of the customer's context.

Step 2.3: Refresh access token when expired

Your access token expires periodically. This step explains how to refresh the access token using the refresh token provided with your last access token.

Use HTTP Basic Authorization when sending the POST request as shown below:

Authorization: Basic <token>

To create the basic token, combine the client_id and the client_secret you retrieved after creating the app with colon (:), and then encode in Base64 as shown here:

Base64(<client_id>:<client_secret>)

Following is the URL for the HTTP POST request:

https://app.gong.io/oauth2/generate-customer-token?
grant_type=refresh_token&refresh_token=eyJlbmMiOiJBMjU2R0NNIiw
YWxnIjoiZGlyIn0..S_6dW2iO3QJj_D0s.Sa7P1N
y1XYsIgNDtAffPG3kh0ovf0_QPTXitYpUdRztXWGmkZrUQHFVbAs41ZKuB
wSIJSfyvJdKnIruZ
1WN_i.hajm9Bxv7JInrX503iGeZw&validity_duration=600

The generate-customer-token has the following parameters:

refresh_token: is the refresh token you received with your last access token (step 3, or step 4 if you're refreshing)
validity_duration: (optional) defines the number of seconds the token is valid for. By default, the token is valid for 1 day. Include this parameter if you want to change the default amount of time the token is valid for.

The generate-customer-token response is as follows:

{
"access_token": "eyJhbG[...]9pDQ",
"refresh_token": "eyJhbF[...]5lSA",
"expires_in": 525600,
"token_type": "Bearer",
"scope": "api:calls:create api:calls:read:basic”
<!-- this parameter is only returned by the generate-customer-token as part of data residency support -->
"api_base_url_for_customer": "https://company-17.api.gong.io"
}

The response includes the access token which by default is valid for 1 day. The token should be used in the Bearer token authentication in the Gong Public API, and a refresh token for the future.

Menu

Comments

CONFIDENTIAL