1. Gong Help Center
  2. Configuring Gong
  3. Integration Partners Hub

Menu

Create an app for Gong

Follow
Jeffrey Aftel
  • Updated

We are in the process of changing the way apps for Gong are created to support data residency regulations. This involves changing the API endpoints you call and new parameters added to the functions. This article covers both methods of creating an app for Gong. If you already have developed an app, you will see the changes you need to make so that your app will comply with 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.

  1. In your company's Settings page, click API and click the Integrations tab.

  2. Click Create Integration.

  3. In the Integration details area, enter your integration name and a description.

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

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

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

  7. 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, you need to establish a UI component that will lead 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 endpoing 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 will remain 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

For apps that support data residency:

To exchange the access code for an access token, pass the access code to the /generate-customer-token endpoint

For apps that don't support data residency:

To exchange the access code for an access token, pass the access code to the /generate-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 with data residency support:

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

Following is the URL for the HTTP POST request without data residency support:

https://app.gong.io/oauth2/generate-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 following parameters are passed:

  • code is the access code you retrieved in Step 2.1.

  • client_id matches the Client ID of the Gong OAuth application that you created.

  • redirect_uri is the callback location where the user-agent will be 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 response will look like this:

{
"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).

As part of data residency support, 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 will expire periodically. Follow the instructions in this step 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 with data residency support:

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

Following is the URL for the HTTP POST request without data residencyt support:

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

Note that these parameters are passed:

  • refresh_token is the refresh token that 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 response will look like this:

{
"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"
}

As in step 2.2, 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.

As part of data residency support, 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 3: Get started with your app

Now is the time to create your app! When you're ready - go here to learn how to set up a sandbox and test it.