Using custom authorization with the integration builder

<div class="article-banners">
<div id="docs-wmp-link"><a href="https://support.zendesk.com/hc/en-us/articles/5411234991258-plan" target="_blank" rel="noopener noreferrer">What's my plan?</a></div>
<div class="article-banner" id="suite_all"><figure class="wysiwyg-table wysiwyg-table-align-left"><table style="margin-left: 0px; margin-right: auto;"><tbody><tr>
<td><strong>All Suites</strong></td>
<td>Team, Growth, Professional, Enterprise, or Enterprise Plus</td>
</tr></tbody></table></figure></div>
<div class="article-banner" id="support_all"><figure class="wysiwyg-table wysiwyg-table-align-left"><table style="margin-left: 0px; margin-right: auto;"><tbody><tr>
<td><strong>Support</strong></td>
<td>Team, Professional, or Enterprise</td>
</tr></tbody></table></figure></div>
</div><div class="body">
<p>The <a href="https://support.zendesk.com/hc/en-us/articles/8357756844442">integration builder</a> supports standard authorization types, including API keys, bearer tokens, username and password, and OAuth 2.0. However, based on your organization’s needs and workflows, standard authorization might not be sufficient. That’s why the integration builder also supports a custom auth-only integration type that works with your organization’s authentication and authorization solutions.</p>
<p>This article contains the following topics:</p>
<ul>
<li data-list-item-id="e3bfe3cb68eaa6ac228c2beb5ec74efd4"><a href="#h_01J8MXSSKDV5ZTW5T1A2SFRV1T">About custom authorization</a></li>
<li data-list-item-id="eecfe472ca2d0161f3e925cb49b964a4c"><a href="#h_01J8MY2GKQWV4J4KQ3A8HBXF8M">Configuring custom authorization</a></li>
<li data-list-item-id="e365fd700bf3bd3d916f3da53896506d5"><a href="#h_01JTNSPT2D3E3MA2W96W300H3J">Creating the data integration</a></li>
<li data-list-item-id="e53336444d7b75c88f140d7ac5f227ddc"><a href="#h_01J8MY2RH9JS06CZ0GJDFHZZ67">Testing custom authorization</a></li>
</ul>
<h2 id="h_01J8MXSSKDV5ZTW5T1A2SFRV1T">About custom authorization</h2>
<p>The custom auth-only integration makes a request for a token and its expiry, which it then passes to the data or main integration for authorization to then make the request for the data.</p>
<p>Overall, the custom authorization flow is as follows:</p>
<ol>
<li data-list-item-id="e7a278d8622c28c98abcbd843df8bf8a7">
<strong>Authorization request.</strong> The configured auth-only integration sends a request to the server, asking for permission to retrieve an access token. If the server authenticates the request (coming from AI agents), it authorizes the retrieval of the access token and, if available, its expiration time.</li>
<li data-list-item-id="e5808d52cda80fc331b07be489b5347ef">
<strong>Handling the token.</strong> After the server responds with the access token, the integration stores two key pieces of information: the token parameter itself and its expiresIn parameter, which determines how long the token is valid.</li>
<li data-list-item-id="e16a9d5b6266e35055b2dd044020093bf">
<strong>Passing the token to the data integration.</strong> These two parameters (token and expiresIn) are passed to the next step, which is the data integration. The token is used to authenticate subsequent requests made by the data integration. The token is set and handled internally, and is never exposed to the session or conversation data.</li>
<li data-list-item-id="ef6a8ae97e49a74dcdd3f98092f5d66ab">
<strong>Custom authorization request for data.</strong> With the access token in place, the data integration is now authorized to retrieve the necessary data, which is used to enrich the conversation.</li>
</ol>
<p>The flowchart below illustrates the custom authorization flow.</p>
<p><img src="https://zen-marketing-documentation.s3.amazonaws.com/docs/en/ultimate_custom_auth_flowchart.png" width="600"></p>
<h2 id="h_01J8MY2GKQWV4J4KQ3A8HBXF8M">Configuring custom authorization</h2>
<p>You configure custom authorization as part of the normal process of creating an integration in the integration builder.</p>
<div class="note">
<span class="notetitle">Note:</span> Don't use more than one environment at a time for the custom authorization. If you want to split into Production, Sandbox, and so forth, split them into separate authorization integrations.</div>
<p><strong>To configure custom authorization in the integration builder</strong></p>
<ol>
<li data-list-item-id="e52a32414346a34a50c507dd359b66c67">In the main menu, click <strong>API Integrations</strong>.</li>
<li data-list-item-id="e0f704d9addb2e73edc0b4bad4f66c7ec">In the top right, click <strong>Add Integration</strong>.</li>
<li data-list-item-id="ee50edfd003aa43d14d19f22c96af8dff">In the <strong>Add Integration</strong> window:<ol>
<li data-list-item-id="e56056533f19fa207448decf9291f2ab4">In the <strong>Integration name</strong> field, give your integration a descriptive name.</li>
<li data-list-item-id="e0a1f9ed2c04ce68c8b13e40bdf898809">(Optional) In the <strong>Description</strong> field, enter a description of the integration that helps you remember what it’s for.</li>
<li data-list-item-id="e2136525572961faf765575cb0821d7a9">Select <strong>Setup as an ‘auth only’ integration</strong>.</li>
<li data-list-item-id="e52a69964f3b21aa928ff8d3e8ce1dd05">Click <strong>Save</strong>.<br><img src="https://zen-marketing-documentation.s3.amazonaws.com/docs/en/ultimate_custom_auth_add_integration.png" width="400">
</li>
</ol>
</li>
<li data-list-item-id="eb120e26fa6c78f2bd803786ec907c0a4">In the left sidebar, under <strong>Scenarios</strong>, hover over <strong>Failure</strong>, select the options menu (<img src="https://zen-marketing-documentation.s3.amazonaws.com/docs/en/macros_edit_menu_icon.png">) and select <strong>Delete</strong>. <br>For custom authorization, you only need Success scenarios and must delete the Failure scenarios. However, you can’t delete the Fallback scenarios.<br><img src="https://zen-marketing-documentation.s3.amazonaws.com/docs/en/ultimate_custom_auth_delete_failure.png" width="300">
</li>
<li data-list-item-id="ece7dbaf1d214f202ea94a4bb4170e65d">On the <strong>Success</strong> scenarios page, create two session parameters (by clicking the <strong>+</strong> button) with the following details:<ul>
<li data-list-item-id="e535d0e590cf165342185ddcb5bcf798f">token<ul>
<li data-list-item-id="e6789c9545d248aeec6083484a5043bcd">
<strong>Key:</strong> token <em>(must be written exactly like this)</em>
</li>
<li data-list-item-id="e26e41a7c9e9a007724cbe2cbe9fa4050">
<strong>Query:</strong> Enter a value that defines the token. For example: data.access_token</li>
</ul>
</li>
<li data-list-item-id="ef19e9175023b97744dc4e29f467e49e7">expiresIn<ul>
<li data-list-item-id="ed3aa3457ec15548446461ffd0b1a3ac5">
<strong>Key:</strong> expiresIn <em>(must be written exactly like this)</em>
</li>
<li data-list-item-id="e3fa745415a4f7504766cef6d5ef6f385">
<strong>Query:</strong> Enter a value that defines the token expiry. For example: data.expires_in<br>Token expiry may not be part of your data response. In that case, you can hardcode a value (in seconds) of your choice. For example: 3600<br>We strongly recommend setting a token expiry. If you run into an error when testing, this is the amount of time you’ll need to wait before a new token is issued. With no expiry, the token is set indefinitely, meaning you won’t be able to issue a new one during troubleshooting.<br><img src="https://zen-marketing-documentation.s3.amazonaws.com/docs/en/ultimate_custom_auth_params.png" width="600">
</li>
</ul>
</li>
</ul>
</li>
<li data-list-item-id="ef27c14e94507fec1aa774f29d205f569">Click <strong>Save</strong>.</li>
</ol>
<h2 id="h_01JTNSPT2D3E3MA2W96W300H3J">Creating the data integration</h2>
<p>Next, create the data integration that will use the custom auth only integration you created in the steps above. Do this as you normally would when creating a new integration. For help, see <a href="https://support.zendesk.com/hc/en-us/articles/8357756844442">Integration Builder Explained</a>.</p>
<p><strong>To create the data integration</strong></p>
<ol>
<li data-list-item-id="e71252f4f76e600a8e6dd924cd512e47b">In the left sidebar, under <strong>Environments</strong>, select an environment (such as Production).</li>
<li data-list-item-id="eea5f3e1e81d3ff968a67acb926d0db73">On the <strong>Authorization</strong> tab, in the <strong>Authorization Type</strong> drop-down field, select <strong>Custom</strong>.</li>
<li data-list-item-id="ebd0b00a34863eade10ee5422a1f673c7">In the <strong>API authorization integration</strong> drop-down field, select the custom auth-only integration you created above.<br><img src="https://zen-marketing-documentation.s3.amazonaws.com/docs/en/ultimate_custom_auth_type.png" width="400">
</li>
<li data-list-item-id="e7f54dd4dc5101dc5c4deaac26a0af293">Select the <strong>Headers</strong> tab and click <strong>Add Header</strong>.</li>
<li data-list-item-id="ecd322dad93ec16ad475bedc5cd66601e">Fill in the following fields:<ul>
<li data-list-item-id="e6e9cfaf47d1bcf297314e8b4f9d86e88">
<strong>Key:</strong> Authorization</li>
<li data-list-item-id="e47b91ed5d6d1ebde2b8b9c9a12e3e321">
<strong>Value:</strong> Bearer {{apiToken}} <em>(must be written exactly like this)</em><br><img src="https://zen-marketing-documentation.s3.amazonaws.com/docs/en/ultimate_custom_auth_header.png" width="400">
</li>
</ul>
</li>
<li data-list-item-id="e8dd170b5ca69b5c78d86fe0acd1c2fb3">Click <strong>Save</strong>.</li>
</ol>
<h2 id="h_01J8MY2RH9JS06CZ0GJDFHZZ67">Testing custom authorization</h2>
<p>After you configure your custom auth-only integration, we recommend testing it. For help, see <a href="https://support.zendesk.com/hc/en-us/articles/8357756844442-Integration-Builder-Explained#4-test-functionality">Test Functionality</a>.</p>
<h3 id="h_01J8MY2WEVQY7BYG1HHZPJ6J66">Troubleshooting statusCode: null</h3>
<p>Additionally, when testing your integration, you might encounter a “statusCode: null” message, as shown in the image below:<br><img src="https://zen-marketing-documentation.s3.amazonaws.com/docs/en/ultimate_custom_auth_statusCode_null.png" width="400"></p>
<p>First, double-check that your custom auth-only integration has been correctly configured according to the <a href="#h_01J8MY2GKQWV4J4KQ3A8HBXF8M">steps above</a>.</p>
<p>Next, take note of where the error is occurring. If it’s in the auth integration, something likely isn’t configured correctly, or the URL you’re making the request to might be wrong. In this case, we recommend checking with engineers on your side, as they may be able to provide more information on what’s wrong.</p>
<p>If you’ve taken the steps above and are still encountering this error, wait until the token expires and try again.</p>
<p>If you’ve tried all of these troubleshooting steps and the integration still isn’t working, contact your CSM for additional assistance.</p>
<p> </p>
<script id="docs-schema-markup" type="application/ld+json">
{
"@context": "https://schema.org",
"@type": "TechArticle",
"@id": "https://support.zendesk.com/hc/en-us/articles/8357749813658",
"url": "https://support.zendesk.com/hc/en-us/articles/8357749813658-Using-custom-authorization-with-the-integration-builder",
"headline": "Using custom authorization with the integration builder",
"description": "You can configure a custom authorization integration to handle token-based authentication and pass the token to a data integration for authorized data retrieval within the integration builder.",
"articleSection": "Integrating other platforms with advanced AI agents",
"datePublished": "2024-11-11T22:25:15+00:00",
"dateModified": "2025-09-05T23:12:25+00:00",
"inLanguage": "en-US",
"mainEntityOfPage": {
"@type": "WebPage",
"@id": "https://support.zendesk.com/hc/en-us/articles/8357749813658"
},
"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",
"softwareAddOn": {
"@type": "SoftwareApplication",
"name": "AI agents",
"@id": "https://support.zendesk.com/hc/en-us/sections/8988994355994"
}
}
}
</script>
</div>