Securing API connections in App Builder

<div class="body">
<p class="p">App Builder supports a range of standard API authentication methods, including API keys
and OAuth 2.0. Some setup is always required. You’ll need to provide credentials like an
API key from your provider or OAuth client credentials.</p>
<p class="p">When an app built with App Builder needs to authenticate with an external API,
credentials are never written into the app’s code. Instead, App Builder creates a <a class="xref" href="https://developer.zendesk.com/documentation/apps/app-developer-guide/making-api-requests-from-a-zendesk-app/#using-secure-settings" target="_blank">secure setting</a> for each secret. A secure
setting allows you to enter and store credentials using Zendesk’s application proxy.
These secrets are encrypted and can only be used for API calls to the domains you
specify, much like a password manager limited to approved services.</p>
<p class="p">Credentials managed this way are never visible to agents, end users, or exposed in
browser code, even if a user account is compromised. Agents are limited to their
authorized actions and cannot use these credentials to gain extra access, significantly
reducing the risk of credential theft or misuse.</p>
<p class="p">Admins are responsible for protecting all shared secrets and passwords. Secure settings
help by limiting exposure and access, but best practices still apply.</p>
<div class="note" id="topic_az2_ybj_jhc__note_xtm_jcj_jhc">
<span class="notetitle">Note:</span> Never enter passwords or sensitive credentials directly in AI
prompts. While App Builder and other AI coding platforms are designed to reject and
avoid storing them, any prompt content may be logged. Only use the secure settings for
entering credentials.</div>
<p class="p">To strengthen security, you are prompted to enter credentials each time an app is tested
or published. Keep track of your credentials and notes during development, so you can
quickly update the test environment as you iterate on your app.</p>
</div>
<div aria-labelledby="ariaid-title2" class="topic nested1" id="topic_apc_v2j_jhc">
<h2 class="title topictitle2" id="ariaid-title2">Example: Creating an OAuth connector for Google Sheets</h2>
<div class="body">
<p class="p">Google Sheets can be integrated through its API, which is secured using OAuth to
prevent unauthorized access. When prompted to connect to a Google Sheet, App Builder
automatically guides you through the OAuth connection steps, including configuration
in the Google Cloud Dashboard. </p>
<p class="p">The following example creates an app that reads your spreadsheet and retrieve data
from its rows. For this example, a Google Sheet is created, and the "risk subtype"
and "overall risk" custom fields are set up in Zendesk. A CSV file is then used to
upload 278 risk values to the custom field and to populate the Google Sheet.</p>
<p class="p">In this example, the app reads a sheet containing ticket subtypes (represented by a
custom multi-select dropdown field in Zendesk). Each subtype is matched to a row in
the sheet to determine its priority. For example, some subtypes may indicate an
urgent priority while others are low priority. The app finds the highest priority
among all selected risk subtypes on the ticket and assigns it to the ticket’s
priority field. The subtype list is updated regularly and maintained in the Google
Sheet by another team, allowing the integration to use the most current data without
manual updates.</p>
</div>
<div aria-labelledby="ariaid-title3" class="topic nested2" id="topic_upk_f3j_jhc">
<h3 class="title topictitle3" id="ariaid-title3">Creating the prompt and reviewing the plan</h3>
<div class="body">
<p class="p">In this example, the following prompt is used. It isn't necessary to include
extensive details or the Google Sheets ID. App Builder prompts for any
additional information as needed.</p>
<p class="p" dir="ltr">
<img class="image img-screenshot" id="topic_upk_f3j_jhc__image_fg1_g3j_jhc" src="https://zen-marketing-documentation.s3.amazonaws.com/docs/en/app-builder-api-prompt.png" width="500"></p>
<p class="p">App Builder generates a plan that outlines the features to be included in the
app, along with recommendations for potential enhancements. In this example, the
plan is approved as presented, but it is also possible to select additional
options or continue refining the plan through further conversation.</p>
</div>
</div>
<div aria-labelledby="ariaid-title4" class="topic nested2" id="topic_btn_3jj_jhc">
<h3 class="title topictitle3" id="ariaid-title4">Reading the spreadsheet</h3>
<div class="body">
<p class="p">App Builder recognizes that it needs to access the spreadsheet and prompts for
the necessary spreadsheet details, such as the URL and the name of the sheet
within the file. By default, the sheet name is “Sheet1,” but in this example
“Risks” is used for clarity. At this stage, credentials are not yet
required.</p>
<p class="p" dir="ltr">
<img class="image img-screenshot" id="topic_btn_3jj_jhc__image_zkw_zjj_jhc" src="https://zen-marketing-documentation.s3.amazonaws.com/docs/en/app-builder-api-plan.png" width="500"></p>
<p class="p">In this example, App Builder needs more details to proceed. Providing additional
information about the expected sheet structure helps App Builder to correctly
interpret and process the data it retrieves from the spreadsheet.</p>
<p class="p" dir="ltr">
<img class="image img-screenshot" id="topic_btn_3jj_jhc__image_zfc_lkj_jhc" src="https://zen-marketing-documentation.s3.amazonaws.com/docs/en/app-builder-api-approved.png" width="500"></p>
</div>
</div>
<div aria-labelledby="ariaid-title5" class="topic nested2" id="topic_od1_vlj_jhc">
<h3 class="title topictitle3" id="ariaid-title5">Building the modules</h3>
<div class="body">
<p class="p">App Builder passes the approved plan to its build modules, which reference
documentation on Zendesk ticket objects (such as fields and events) and UI
display standards (using the React framework). These modules then generate the
required app components and provide a summary of the work completed.</p>
<p class="p" dir="ltr">
<img class="image img-screenshot" id="topic_od1_vlj_jhc__image_rtl_l5j_jhc" src="https://zen-marketing-documentation.s3.amazonaws.com/docs/en/app-builder-gather.png" width="500"></p>
<p class="p">App Builder then describes the built product, which can be used as a starting
point for future enhancements.</p>
<p class="p" dir="ltr">
<img class="image img-screenshot" id="topic_od1_vlj_jhc__image_mjh_q5j_jhc" src="https://zen-marketing-documentation.s3.amazonaws.com/docs/en/app-builder-app-created.png" width="500"></p>
</div>
</div>
<div aria-labelledby="ariaid-title6" class="topic nested2" id="topic_wqq_t5j_jhc">
<h3 class="title topictitle3" id="ariaid-title6">Creating the OAuth connection</h3>
<div class="body">
<p class="p">App Builder next provides step-by-step instructions for creating a read-only
OAuth token for Google Sheets. If you’re connecting to another service, the
process may involve different steps. Whenever App Builder recognizes the
external system, it offers guidance to help you set up a successful
connection.</p>
<div class="note" id="topic_wqq_t5j_jhc__note_lj3_1vj_jhc">
<span class="notetitle">Note:</span> Be sure to review the step for the redirect URI (the
last bullet in Step 3 below). If you don't see it, scroll up in the instructions
to locate it.</div>
<p class="p" dir="ltr">
<img class="image img-screenshot" id="topic_wqq_t5j_jhc__image_kn3_kvj_jhc" src="https://zen-marketing-documentation.s3.amazonaws.com/docs/en/app-builder-oauth-setup-instruct.png" width="500"></p>
<p class="p">After completing these steps, you'll have the option to download the credentials
as a JSON file. This lets you reuse the credentials for future connections
without needing to create new ones. For example:</p>
<div class="p">
<pre class="pre codeblock wysiwyg-code-block" id="topic_wqq_t5j_jhc__codeblock_zy1_tvj_jhc"><code>{
"web": {
"client_id": "000000000000-cabcderfp8mq12345678b21m9aomgr.apps.googleusercontent.com",
"project_id": "test-api-use-12345",
"auth_uri": "https://accounts.google.com/o/oauth2/auth",
"token_uri": "https://oauth2.googleapis.com/token",
"auth_provider_x509_cert_url": "https://www.myapis.com/oauth2/v1/certs",
"client_secret": "PIR-UAE1234567abc123234546_"
}
}
</code></pre>
</div>
</div>
</div>
<div aria-labelledby="ariaid-title7" class="topic nested2" id="topic_tvz_yvj_jhc">
<h3 class="title topictitle3" id="ariaid-title7">Previewing and testing the app</h3>
<div class="body">
<p class="p">The built-in preview displays your app using mock data, giving you an idea of its
appearance and features.</p>
<p class="p" dir="ltr">
<img class="image img-screenshot" id="topic_tvz_yvj_jhc__image_rmw_gwj_jhc" src="https://zen-marketing-documentation.s3.amazonaws.com/docs/en/app-builder-preview.png" width="400"></p>
<p class="p">Once your app is ready, click <strong class="ph b">Test</strong> or <strong class="ph b">Publish</strong> and App Builder will
guide you through the OAuth authorization steps needed to connect to your data
source. Be sure to provide the client callback URL to your OAuth provider as
part of this process.</p>
<div class="note" id="topic_tvz_yvj_jhc__note_ttn_twj_jhc">
<span class="notetitle">Note:</span>
<p class="p">You'll need to re-enter the callback URL each time you test to ensure that
your credentials remain secure and up to date. In a production environment,
this step is typically only required during installation or major
changes.</p>
</div>
<p class="p" dir="ltr">
<img class="image img-screenshot" id="topic_tvz_yvj_jhc__image_i1g_vwj_jhc" src="https://zen-marketing-documentation.s3.amazonaws.com/docs/en/app-builder-oauth-configure.png" width="500"></p>
<p class="p">After connecting, Google prompts you to sign in with an authorized account, which
doesn’t need to be your Zendesk admin user. When the authentication succeeds,
you’ll see a confirmation popup and the App Builder displays a new Test button.
Clicking <strong class="ph b">Test</strong> validates the connection using your real data source.</p>
<p class="p" dir="ltr">
<img class="image img-screenshot" id="topic_tvz_yvj_jhc__image_nhw_1xj_jhc" src="https://zen-marketing-documentation.s3.amazonaws.com/docs/en/app-builder-oauth-verified.png" width="300"></p>
<p class="p" dir="ltr">
<img class="image img-screenshot" id="topic_tvz_yvj_jhc__image_j4b_cxj_jhc" src="https://zen-marketing-documentation.s3.amazonaws.com/docs/en/app-builder-connection-success.png" width="500"></p>
</div>
</div>
</div><script id="docs-schema-markup" type="application/ld+json">{
"@context": "https://schema.org",
"@type": "TechArticle",
"@id": "https://support.zendesk.com/hc/en-us/articles/9970429843610",
"url": "https://support.zendesk.com/hc/en-us/articles/9970429843610-Securing-API-connections-in-App-Builder",
"headline": "Securing API connections in App Builder",
"description": "You learn how to securely manage API authentication credentials using encrypted secure settings and OAuth connections when building apps that integrate with external APIs like Google Sheets.",
"articleSection": "Extending Zendesk",
"datePublished": "2025-11-20T16:40:06+00:00",
"dateModified": "2025-11-21T03:02:50+00:00",
"inLanguage": "en-US",
"mainEntityOfPage": {
"@type": "WebPage",
"@id": "https://support.zendesk.com/hc/en-us/articles/9970429843610"
},
"author": {
"@type": "Organization",
"name": "Zendesk",
"@id": "https://www.zendesk.com"
},
"publisher": {
"@type": "Organization",
"name": "Zendesk",
"@id": "https://www.zendesk.com"
},
"isPartOf": {
"@type": "WebSite",
"name": "Zendesk Help",
"@id": "https://support.zendesk.com/hc/"
},
"about": {
"@type": "SoftwareApplication",
"name": "Zendesk",
"@id": "https://www.zendesk.com"
}
}</script>