--- title: "Create an OAuth app for Gong" slug: "create-an-app-for-gong" updated: 2026-01-18T14:57:51Z published: 2026-01-18T14:57:51Z 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 > **Where to go:**Admin center > Settings > Ecosystem > API 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. ## 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. ## **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**: > **Where to go:**Admin center > Settings > Ecosystem > API 1. In the **INTEGRATIONS** tab, click **Create Integration**. 2. In the **Integration details** area, enter your integration name and a description, and short description. Once your integration is 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. 3. 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 4. 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. 5. 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** - **Emails of contacts in your organization**: list of emails of people in your organization that Gong can reach out to - **Domains**: list of your organization’s domains 6. Select the iFrame toggle 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. 7. 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) ## **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. ## **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. ## **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 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_        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(:) ``` Following is the URL for the HTTP POST request: ```plaintext 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 - **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. ## **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).