--- title: "Create an OAuth app for Gong" slug: "create-an-app-for-gong" updated: 2026-10-07T12:27:17Z published: 2026-10-07T12:27:17Z canonical: "help.gong.io/create-an-app-for-gong" --- > ## Documentation Index > Fetch the complete documentation index at: https://help.gong.io/llms.txt > Use this file to discover all available pages before exploring further. # Create an OAuth app for Gong > **Who can use this**: Tech admin > > **Available on**: Any Gong plan This article covers how to create an app which integrates with Gong to list on the [Gong Collective](https://www.gong.io/collective/), and which complies with data residency regulations. By utilizing our APIs you can create apps which use both the backend or frontend public APIs. Setting up an app to integrate with Gong includes the following steps: 1. Ensure you have [credentials](/v1/docs/create-an-app-for-gong#request-a-developer-instance) to log into your Gong developer instance 2. [Submit](/v1/docs/create-an-app-for-gong#submit-your-integration-details-to-gong) details of the integration 3. Set up [oAuth](/v1/docs/create-an-app-for-gong#set-up-oauth-access) authentication if required 4. Create your app and [test it](/v1/docs/set-up-a-sandbox) 5. Update your integration details in Gong if needed 6. [Publish the app](/v1/docs/list-your-app-in-the-gong-collective) in the Gong Collective. Your customers can then install the app on their instance of Gong, and their reps can then embed your HTML content to their emails. In addition, you should decide which APIs you need in order to create your app. ## Step 1: Request a developer instance Fill in this [form](https://collective.gong.io/application_forms/become-a-gong-technology-partner/partner_applications/new) to get a Gong developer instance. This can take up to five working days. Once the instance is set up, you will receive a login credentials so that you can start to test your app. ## **Step 2: Submit your integration details to Gong** Provide Gong with information on your integration, and receive the keys required to set up oAuth access. You can edit this information later if needed. **To submit your integration details to Gong**: 1. From the left sidebar, click **Admin center**. 2. In the **Settings** tab, click **API** in the **Ecosystem** card. 3. In the **Integrations** tab, click **CREATE INTEGRATION**. 4. In the **General details** area, enter your integration name and a description, and short description. Once published, your integration name and short description are displayed in the integrations page, and the description is displayed on the specific page for your integration. 5. In the **App Branding** 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 6. Select an option under **Authorization context** (this setting can’t be edited once the integration is set up): - **Shared access**: All company data is available based on the selected scopes. Tech admin must connect integrations with shared access. - **Personal access**: The integration can only access the data of the user who authorized the integration. > [!NOTE] > Note: > > Personal access is supported for > > - api:ai-ask:read > - api:ai-briefer:read > - All mcp scopes > > Authorization for other scopes use shared access. 7. In the **Required authorization scopes** area, select the scopes that your app needs. Check the [API documentation](https://app.gong.io/settings/api/documentation#overview) to see which APIs use which scopes. When installing your app, customers will be asked to grant access to the entities accessed by these scopes. 8. Add the links requested for your app: - **Redirect URI needed for the OAuth authentication:** only relevant if you are setting up OAuth authentication - **Link to your integration's privacy policy page** - **Link to your terms and conditions page** - **Link to your integration's help article** - **Link to page in your integration where authorization process begins** 9. In **Operations & Domain,** provide the emails and domains of people in your company that Gong can contact. 10. In **Security**, set which IP addresses can access the integration. You can also provide this information before the app is published to the Gong Collective. 11. In **Advanced Settings**, select the **iFrame Integration** toggle if you want to create a frontend integration with Gong. For details on the JavaScript SDK see [Build an app to display content in the Gong email composer](/v1/docs/build-an-app-to-display-content-in-the-gong-email-composer). You must provide the following: - Email composer: To enable adding suggested content to an email, provide a URL to your app which can add media or other content in the Gong email composer. - Account information: To enable adding content relevant to an account in the Engage account or pipeline pages, provide a URL to an app which returns data for that account. - Allowed origins: A list of static URLs that the iFrame can load. If you need to load dynamic sub-domains, you must configure this using the integrations-settings API. 12. Select the **Link Personalization** toggle to create an app that supports link personalization for emails sent in Gong. 13. Click **Save**. A new row appears in the list of integrations, with the **Client ID** and the **Client Secret**. You can also see the app status and edit the app details. ![](https://cdn.us.document360.io/2837c190-3ec8-4120-9116-6d427e774667/Images/Documentation/integrationList(2).png) ## **Step 3: Set up OAuth access** If your app requires OAuth access, run this procedure once to set up OAuth. Use the client ID and the client secret you got from Gong and follow these steps so that you can access Gong's API on behalf of our mutual customers. This must be done by a tech admin. This follows the standard OAuth procedures as per RFC 6749, and explains the details of the protocol. > [!NOTE] > Note: > > Gong doesn’t support user level OAuth. Authentication happens once on a global level. ## **Step 4: Use the authorization code flow** Enter the authorize URL in a browser as follows: ```plaintext https://app.gong.io/oauth2/authorize?        client_id=&response_type=code&scope=&redirect_uri=&state=296bc9a0-a2a2-4a57 ``` The endpoint receives the following parameters: - **client_id** matches the Client ID provided by Gong when you registered your integration. - **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. This is a space-delimited list of the scopes you selected when you registered your integration. - **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 registering your integration. - **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](https://www.rfc-editor.org/rfc/rfc6750.txt). If the user does not have an active Gong sign-in session, you will have to sign into Gong. Make sure you sign in with the credentials of a tech admin. 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: ```plaintext 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 5: Exchange the code for an access token** This should be done in a client such as Postman that can run a post request. Copy the code in the url from the previous step and pass it via the `/generate-customer-token` endpoint. Use HTTP Basic Authorization when sending the POST request as shown below: ```plaintext Authorization: Basic ``` To create the basic token, combine the client_id and the client_secret you received from Gong with a colon (:), and then encode in Base64 as shown here: ```plaintext Base64(:) ``` Following is the URL for the HTTP POST request: ```plaintext POST https://app.gong.io/oauth2/generate-customer-token Content-Type: application/x-www-form-urlencoded Authorization: Basic grant_type=authorization_code&code=&redirect_uri=https://example.com/oauth_cb&validity_duration=600 ``` The `generate-customer-token` endpoint receives the following parameters: - **code**: the access code you retrieved in [Use the authorization code flow](/v1/docs/create-an-app-for-gong#use-the-authorization-code-flow). - **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 [Use the authorization code flow](/v1/docs/create-an-app-for-gong#use-the-authorization-code-flow). - **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: ```plaintext {        "access_token": "eyJhbG[...]9pDQ",        "refresh_token": "eyJhbF[...]5lSA",        "expires_in": 525600,        "token_type": "Bearer",        "scope": "api:calls:create api:calls:read:basic”        "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 [Refresh access token when expired](/v1/docs/create-an-app-for-gong#refresh-access-token-when-expired)). 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. ### **Refresh access token when expired** Your access token expires periodically. 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: ```plaintext Authorization: Basic ``` 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: ```plaintext Base64(:) ``` Send the request to the following URL, with `grant_type`, `refresh_token`, and `validity_duration` in the request body as `application/x-www-form-urlencoded`, as described in [RFC 6749 §6](https://datatracker.ietf.org/doc/html/rfc6749#section-6): ```plaintext POST https://app.gong.io/oauth2/generate-customer-token Content-Type: application/x-www-form-urlencoded Authorization: Basic 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 - **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: ```plaintext {        "access_token": "eyJhbG[...]9pDQ",        "refresh_token": "eyJhbF[...]5lSA",        "expires_in": 525600,        "token_type": "Bearer",        "scope": "api:calls:create api:calls:read:basic”        "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. 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 6: Get started with your app** Now is the time to create your app. Set up a [sandbox](/v1/docs/set-up-a-sandbox#UUID-497a0097-e405-738a-4118-22db6ccfd0d5) and test it. A team member who manages and configures the Gong platform and handles CRM integrations, user provisioning, permissions, and system settings. [Find my Tech admin](/v1/docs/find-your-technical-or-business-admin). Access to this feature depends on your [assigned seat](/v1/docs/plans-and-seats).