Creating connections to external services for custom actions

<body>
<p id="docs-hc-snippet" style="display: none;">A connection supports one of the following API authentication methods:</p>
<div class="article-banners">
<div id="docs-wmp-link">
<a href="https://support.zendesk.com/hc/en-us/articles/5411234991258-plan" rel="noopener" target="_blank">What's my plan?</a>
</div>

<div class="article-banner" id="suite_all">
<table>
<tbody>
<tr>
<td>
<strong>All Suites</strong>
</td>
<td>Team, Growth, Professional, Enterprise, or Enterprise Plus</td>
</tr>
</tbody>
</table>
</div>

</div>
<div id="docs-ai-summary">
<p id="docs-ai-summary-toggle">Summary: <span id="up-triangle">◀</span><span id="down-triangle">▼</span></p>
<p id="docs-ai-summary-content">You can create connections to securely store API credentials for external services using API key, Basic auth, Bearer token, or OAuth 2.0. These connections authenticate REST API calls in auto assist actions. You can create custom connections or use pre-built connectors, specify allowed domains to restrict usage, and configure OAuth clients with necessary credentials. This helps integrate external systems like Slack or Shopify safely and effectively.</p>
</div>

<div class="body">

<div class="p">
<div class="note fastpath">
<span class="fastpathtitle">Location: </span> <span class="ph">Admin Center &gt; Apps and integrations &gt; Connections &gt;
Connections</span>
</div>
</div>
<div class="p" id="topic_xxd_5yp_rvb__note_owy_qnb_hbc">A connection lets you safely store API credentials for a service or system,
such as Slack or Shopify. You can use a connection to authenticate REST API calls in
<a class="xref" href="https://support.zendesk.com/hc/en-us/articles/8013439366810" target="_blank">custom actions</a> for auto assist, action flows,
and custom agents. You must be an admin to create connections.<div class="note" id="topic_xxd_5yp_rvb__note_vxf_4fk_f2c">
<span class="notetitle">Note:</span> The instructions in this article also apply to accounts using
using the legacy bot builder <a class="xref" href="https://support.zendesk.com/hc/en-us/articles/4572971586586" target="_blank">Make API call</a> step.</div>
</div>
<div class="p">This article covers the following topics:
<ul class="ul" id="topic_xxd_5yp_rvb__ul_gzn_rly_rvb">
<li class="li"><a class="xref" href="#topic_fyj_ply_rvb">About
connections</a></li>
<li class="li"><a class="xref" href="#topic_wb5_txw_rvb">Creating a custom connection</a></li>
<li class="li"><a class="xref" href="#topic_sxw_df2_ckc">Browsing and connecting to existing connectors</a></li>
<li class="li"><a class="xref" href="#topic_dmc_y23_fvb">Allowed
domain</a></li>
<li class="li"><a class="xref" href="#topic_u5k_qly_rvb">HTTP headers for API
keys</a></li>
</ul>
</div>
</div>
<div aria-labelledby="ariaid-title2" class="topic nested1" id="topic_fyj_ply_rvb">
<h2 class="title topictitle2" id="ariaid-title2">About connections</h2>
<div class="body">
<p class="p">A connection supports one of the following API authentication methods:</p>
<ul class="ul" id="topic_fyj_ply_rvb__ul_lsr_1my_rvb">
<li class="li">API key</li>
<li class="li">Basic authentication</li>
<li class="li">Bearer token</li>
<li class="li">OAuth 2.0</li>
</ul>
<p class="p">This authentication method determines the type of credentials the
connection stores. For example, a basic authentication connection stores a username
and password. After you create a connection, you can't change its authentication
type.</p>
<p class="p">Different APIs support different authentication methods. To determine the
appropriate authentication method for an API call, consult the API's
documentation.</p>
</div>
<div aria-labelledby="ariaid-title3" class="topic nested2" id="topic_gxk_cmy_rvb">
<h3 class="title topictitle3" id="ariaid-title3">HTTP headers for authentication types</h3>
<div class="body">
<div class="p">When you use a connection to authenticate an API call in an auto assist action, Zendesk passes
the connection's credentials in an HTTP header. Zendesk determines this header
based on the connection's authentication type. <table border="1" cellpadding="4" cellspacing="0" class="simpletable" id="topic_gxk_cmy_rvb__simpletable_x21_gmy_rvb" summary="">
<col style="width:50%">
<col style="width:50%">
<thead>
<tr class="sthead">
<th class="stentry" id="d91e115" style="vertical-align:bottom;text-align:left;"> Authentication type </th>
<th class="stentry" id="d91e118" style="vertical-align:bottom;text-align:left;"> HTTP header </th>
</tr>
</thead>
<tbody>
<tr class="strow">
<td class="stentry" headers="d91e115" style="vertical-align:top;"> API key </td>
<td class="stentry" headers="d91e118" style="vertical-align:top;"> Set when you create the connection. See <a class="xref" href="#topic_u5k_qly_rvb">HTTP headers for API
keys</a>
</td>
</tr>
<tr class="strow">
<td class="stentry" headers="d91e115" style="vertical-align:top;"> Basic authentication </td>
<td class="stentry" headers="d91e118" style="vertical-align:top;">
<code class="ph codeph">Authorization: Basic</code>
</td>
</tr>
<tr class="strow">
<td class="stentry" headers="d91e115" style="vertical-align:top;"> Bearer token </td>
<td class="stentry" headers="d91e118" style="vertical-align:top;">
<code class="ph codeph">Authorization: Bearer</code>
</td>
</tr>
<tr class="strow">
<td class="stentry" headers="d91e115" style="vertical-align:top;"> OAuth 2.0 </td>
<td class="stentry" headers="d91e118" style="vertical-align:top;"> Access token is sent to the service in <code class="ph codeph">Authorization:
Bearer</code>
</td>
</tr>
</tbody>
</table>
</div>
<p class="p">For more information about using a connection in an action, see <a class="xref" href="https://support.zendesk.com/hc/en-us/articles/8013439366810" target="_blank">Creating and managing actions for auto
assist</a>.</p>
</div>
</div>
</div>
<div aria-labelledby="ariaid-title4" class="topic nested1" id="topic_u4l_zqz_wxb">
<h2 class="title topictitle2" id="ariaid-title4">Creating an OAuth client</h2>
<div class="body">
<p class="p">An OAuth connection stores an OAuth 2.0 access token for a service or system, such as
Slack, Shopify, or Zendesk.</p>
<p class="p">Before creating a connection with the OAuth 2.0 authentication type, you must
configure an OAuth client. When configuring the OAuth client, you need the client
ID, client secret, authorization URL, token URL, and scopes from the external
system's OAuth configuration interface or admin portal. These credentials are
generated while registering your client application (such as Zendesk) with the
external system. The exact steps vary based on the external service. If required,
set the client's callback URL as
"https://zis.zendesk.com/api/services/zis/connections/oauth/callback".</p>
<div class="p">
<div class="note" id="topic_u4l_zqz_wxb__note_bvw_2rz_wxb">
<span class="notetitle">Note:</span>
We only support connects with external systems that are
compliant with the
<a class="xref" href="https://datatracker.ietf.org/doc/html/rfc6749" target="_blank">OAuth 2.0 Authorization
Framework</a>.
</div>
</div>
<div class="p">You can create OAuth clients using the following OAuth 2.0 grant types:
<ul class="ul" id="topic_u4l_zqz_wxb__ul_vxb_krz_wxb">
<li class="li">Authorization code</li>
<li class="li">Client credentials</li>
</ul>
</div>
<p class="p">The refresh token grant type is supported for OAuth 2.0 clients created using an
authorization code grant type. If the system's access token response includes
non-empty
<a class="xref" href="https://www.oauth.com/oauth2-servers/access-tokens/access-token-response/" target="_blank"><code class="ph codeph">expires_in</code>and
<code class="ph codeph">refresh_token</code></a>
values, the access token is
automatically refreshed using the refresh token.</p>
<p class="p">OAuth 2.0 connections created with a client using the Clients credentials grant type
may include a token expiry value. In these cases, when the token expires, a new
access token is fetched using the same OAuth client.</p>
<div class="p">
<div class="note" id="topic_u4l_zqz_wxb__note_a21_1yx_dyb">
<span class="notetitle">Note:</span>
In some cases, we may refresh the access token multiple
times with a single refresh token. Because some systems implement mechanisms to
prevent resuse of a refresh token, we recommend implementing a grace period if
possible, or using the Client credentials grant type instead.
</div>
</div>
<p class="p"><strong class="ph b">To create an OAuth client</strong></p>
<ol class="ol">
<li class="li"><span class="ph">In <a class="xref" href="https://support.zendesk.com/hc/en-us/articles/4581766374554#topic_hfg_dyz_1hb" target="_blank">Admin Center</a>, click <img class="image" id="topic_u4l_zqz_wxb__image_gtl_gty_wxb" src="https://zen-marketing-documentation.s3.amazonaws.com/docs/en/ac_apps_integrations_icon.png">
<strong class="ph b">Apps and integrations</strong> in the sidebar, then select <strong class="ph b">Connections &gt; OAuth
Clients</strong>.</span></li>
<li class="li">Enter a name for the client. You cannot change this name after you create the
client.</li>
<li class="li">Enter the Client ID. This is a unique identifier assigned to your OAuth client,
similar to a username for your client.</li>
<li class="li">Enter the Client secret. This acts as a password for your client application and
establishes trust between Zendesk and the external system.</li>
<li class="li">(Authorization code grant type only) Enter the Authorization URL. This is the
server URL used to receive an authorization code.</li>
<li class="li">Enter the Token URL. This is the URL used to receive an access token.</li>
<li class="li">Enter a space-separate list of default scopes. Scopes are permissions that
represent what a client application can access on behalf of the user.</li>
<li class="li">Click
<strong class="ph b">Save</strong>
to create the client.</li>
</ol>
</div>
</div>
<div aria-labelledby="ariaid-title5" class="topic nested1" id="topic_wb5_txw_rvb">
<h2 class="title topictitle2" id="ariaid-title5">Creating a custom connection</h2>
<div class="body">
<p class="p">You can create a custom connection in Admin Center from the Connections page.</p>
<p class="p"><strong class="ph b">To create a custom connection</strong></p>
<ol class="ol" id="topic_wb5_txw_rvb__ol_dht_5xw_rvb">
<li class="li"><span class="ph">In <a class="xref" href="https://support.zendesk.com/hc/en-us/articles/4581766374554#topic_hfg_dyz_1hb" target="_blank">Admin Center</a>, click <img class="image" id="topic_wb5_txw_rvb__image_ifr_tww_rvb" src="https://zen-marketing-documentation.s3.amazonaws.com/docs/en/ac_apps_integrations_icon.png">
<strong class="ph b">Apps and integrations</strong> in the sidebar, then select <strong class="ph b">Connections &gt;
Connections</strong>.</span></li>
<li class="li">Click <strong class="ph b">Add connection</strong>.</li>
<li class="li">Select <strong class="ph b">Custom connection</strong>, then click <strong class="ph b">Next</strong>.</li>
<li class="li">Enter a name for the custom connection. You can't change this name after you create the
connection.</li>
<li class="li">Do one of the following:
<ul class="ul" id="topic_wb5_txw_rvb__ul_jxk_vsz_wxb">
<li class="li">(API Key, Basic authentication, Bearer token) Configure the connection's
authentication credentials. The connection uses these details to
authenticate REST API calls to the service or system.</li>
<li class="li">(OAuth 2.0) Select the client to use and optionally enter a
space-separated list of scopes. If you do not enter any scopes, the
default ones specified in the OAuth client are used.</li>
</ul>
</li>
<li class="li">Enter an allowed domain for the connection. You can't change the allowed domain
after you create the connection. For more information, see
<a class="xref" href="#topic_dmc_y23_fvb">Allowed
domain</a>.</li>
<li class="li">Click
<strong class="ph b">Save</strong>
to create the connection.</li>
</ol>
<p class="p">After you've created the connection, you can view its details from the Connections
page in Admin Center. See
<a class="xref" href="https://support.zendesk.com/hc/en-us/articles/5174239310746" target="_blank">Managing connections</a>.</p>
<div class="p">
<div class="note" id="topic_wb5_txw_rvb__note_m4v_4xx_dyb">
<span class="notetitle">Note:</span>
When creating a connection with an OAuth 2.0
authentication type, the scopes included in the external system's access token
response are stored, not the scopes defined when creating the connection. This
value cannot be greater than 255 characters.
</div>
</div>
</div>
<div aria-labelledby="ariaid-title6" class="topic nested2" id="topic_tp5_gp5_kkc">
<h3 class="title topictitle3" id="ariaid-title6">Configuring custom connections to Zendesk APIs</h3>
<div class="body">
<p class="p">Before you can create a custom action that connects to a Zendesk API, you must
create a custom connnection to the Zendesk API using basic authentication. The
username should be specified as the user name with <em class="ph i">/token</em> appended to the
end. For example, <code class="ph codeph">your_username/token</code>. The password must be an
<a class="xref" href="https://support.zendesk.com/hc/en-us/articles/4408889192858" target="_blank">API token</a> generated from the API
tokens page in Admin Center.</p>
</div>
</div>
</div>
<div aria-labelledby="ariaid-title7" class="topic nested1" id="topic_sxw_df2_ckc">
<h2 class="title topictitle2" id="ariaid-title7">Browsing and connecting to existing connectors</h2>
<div class="body">
<p class="p">You can browse and connect to pre-built connectors for popular apps and services.</p>
<p class="p"><strong class="ph b">To browse and connect to existing connectors</strong></p>
<ol class="ol" id="topic_sxw_df2_ckc__ol_rfs_jf2_ckc">
<li class="li"><span class="ph">In <a class="xref" href="https://support.zendesk.com/hc/en-us/articles/4581766374554#topic_hfg_dyz_1hb" target="_blank">Admin Center</a>, click <img class="image" id="topic_sxw_df2_ckc__image_ifr_tww_rvb" src="https://zen-marketing-documentation.s3.amazonaws.com/docs/en/ac_apps_integrations_icon.png">
<strong class="ph b">Apps and integrations</strong> in the sidebar, then select <strong class="ph b">Connections &gt;
Connections</strong>.</span></li>
<li class="li">Click <strong class="ph b">Add connection</strong>.</li>
<li class="li">Select <strong class="ph b">Browse connectors</strong>, then click <strong class="ph b">Next</strong>.</li>
<li class="li">Search for the connector you'd like to connect to, then click
<strong class="ph b">Connect</strong>.</li>
</ol>
</div>
</div>
<div aria-labelledby="ariaid-title8" class="topic nested1" id="topic_dmc_y23_fvb">
<h2 class="title topictitle2" id="ariaid-title8">Allowed domain</h2>
<div class="body">
<p class="p">Each connection requires a URL hostname as an allowed domain. Zendesk only
passes the connection's credentials in API calls to this hostname. Attempts to use
the connection with other hostnames will fail. This helps prevent an accidental leak
of the connection's credentials. After you create a connection, you can't change its
allowed domain.</p>
<p class="p">For example, you can only use a connection with an allowed domain of
"api.example.com" to make API calls to the “https://api.example.com” hostname.</p>
</div>
<div aria-labelledby="ariaid-title9" class="topic nested2" id="topic_lfh_4ny_rvb">
<h3 class="title topictitle3" id="ariaid-title9">Allowed domain requirements</h3>
<div class="body">
<p class="p">A connection's allowed domain can't exceed 128 characters. A subdomain
or domain in the value can't exceed 63 characters. The value must contain a
valid domain name.</p>
<p class="p">A connection always uses an
<code class="ph codeph">https</code>scheme. Other schemes, such as
<code class="ph codeph">ftps</code>, are not supported.</p>
</div>
</div>
<div aria-labelledby="ariaid-title10" class="topic nested2" id="topic_bbk_qny_rvb">
<h3 class="title topictitle3" id="ariaid-title10">Wildcards for allowed domain</h3>
<div class="body">
<p class="p">A connection's allowed domain supports an optional wildcard (*)
subdomain. This lets you use the connection with the bare domain and any
subdomain. For example, you can use a connection with an allowed domain of
<code class="ph codeph">*.example.com</code>to authenticate API calls to "example.com" or
any subdomain of "example.com".</p>
<p class="p">To use a wildcard subdomain, the first two characters of the allowed domain must
be
<code class="ph codeph">*.</code>. You can't use a wildcard in other parts of the hostname.
For example, you can't use a wildcard within a hostname, such as
<code class="ph codeph">exam*.com</code>or
<code class="ph codeph">my-*.example.com.</code></p>
<p class="p">You can't use a wildcard with only a
<a class="xref" href="https://publicsuffix.org/" target="_blank">public domain suffix</a>, such as
<code class="ph codeph">*.com</code>,
<code class="ph codeph">*.com.au</code>, or
<code class="ph codeph">*.myshopify.com</code>. For a list of public suffixes, see the
<a class="xref" href="https://publicsuffix.org/list/public_suffix_list.dat" target="_blank">public suffix list</a>on
publicsuffix.org.</p>
</div>
</div>
</div>
<div aria-labelledby="ariaid-title11" class="topic nested1" id="topic_u5k_qly_rvb">
<h2 class="title topictitle2" id="ariaid-title11">HTTP headers for API keys</h2>
<div class="body">
<p class="p">When you create an API key connection, you must specify an HTTP header
name. When the connection is used to make an API call, Zendesk passes the API key as
the value for this header.</p>
<p class="p">Many APIs use a custom header to accept API keys. To get the appropriate
header name for an API call, consult the API's documentation.</p>
</div>
<div aria-labelledby="ariaid-title12" class="topic nested2" id="topic_dvx_zny_rvb">
<h3 class="title topictitle3" id="ariaid-title12">Header name requirements</h3>
<div class="body">
<p class="p">An API key connection's header name can't exceed 128 characters. The
header name can only contain letters, hyphens (
<code class="ph codeph">-</code>), and
underscores (
<code class="ph codeph">_</code>).</p>
<div class="p">You can't use the following HTTP header names:
<ul class="ul" id="topic_dvx_zny_rvb__ul_zgj_c4y_rvb">
<li class="li"><code class="ph codeph">accept</code></li>
<li class="li"><code class="ph codeph">accept-charset</code></li>
<li class="li"><code class="ph codeph">accept-encoding</code></li>
<li class="li"><code class="ph codeph">accept-language</code></li>
<li class="li"><code class="ph codeph">cache-control</code></li>
<li class="li"><code class="ph codeph">connection</code></li>
<li class="li"><code class="ph codeph">content-md5</code></li>
<li class="li"><code class="ph codeph">cookie</code></li>
<li class="li"><code class="ph codeph">date</code></li>
<li class="li"><code class="ph codeph">expect</code></li>
<li class="li"><code class="ph codeph">from</code></li>
<li class="li"><code class="ph codeph">host</code></li>
<li class="li"><code class="ph codeph">if-match</code></li>
<li class="li"><code class="ph codeph">if-modified-since</code></li>
<li class="li"><code class="ph codeph">if-none-match</code></li>
<li class="li"><code class="ph codeph">if-range</code></li>
<li class="li"><code class="ph codeph">if-unmodified-since</code></li>
<li class="li"><code class="ph codeph">max-forwards</code></li>
<li class="li"><code class="ph codeph">pragma</code></li>
<li class="li"><code class="ph codeph">proxy-authenticate</code></li>
<li class="li"><code class="ph codeph">proxy-authorization</code></li>
<li class="li"><code class="ph codeph">range</code></li>
<li class="li"><code class="ph codeph">server</code></li>
<li class="li"><code class="ph codeph">referer</code></li>
<li class="li"><code class="ph codeph">te</code></li>
<li class="li"><code class="ph codeph">trailer</code></li>
<li class="li"><code class="ph codeph">transfer-encoding</code></li>
<li class="li"><code class="ph codeph">upgrade</code></li>
<li class="li"><code class="ph codeph">user-agent</code></li>
<li class="li"><code class="ph codeph">via</code></li>
<li class="li"><code class="ph codeph">warning</code></li>
<li class="li"><code class="ph codeph">www-authenticate</code></li>
<li class="li">Header names starting with:
<ul class="ul" id="topic_dvx_zny_rvb__ul_vms_5ry_rvb">
<li class="li"><code class="ph codeph">x-amz-</code></li>
</ul>
<ul class="ul" id="topic_dvx_zny_rvb__ul_qwg_d4y_rvb">
<li class="li"><code class="ph codeph">x-amzn-</code></li>
<li class="li"><code class="ph codeph">x-forwarded-</code></li>
<li class="li"><code class="ph codeph">x-zis-</code></li>
</ul>
</li>
</ul>
</div>
</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/5040378297626",
"url": "https://support.zendesk.com/hc/en-us/articles/5040378297626",
"headline": "Creating connections to external services for custom actions",
"description": "You create connections to store API credentials for external services and use them to authenticate REST API calls in custom actions, including OAuth clients, allowed domains, and API key headers.",
"articleSection": "Extending Zendesk",
"datePublished": "2022-10-17T17:36:50+00:00",
"dateModified": "2026-09-02T19:28:17.377785+00:00",
"inLanguage": "en",
"mainEntityOfPage": {
"@type": "WebPage",
"@id": "https://support.zendesk.com/hc/en-us/articles/5040378297626"
},
"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": "Apps and integrations",
"@id": "https://support.zendesk.com/hc/en-us/sections/5283127227418"
}
}
}</script><script id="fast-path-script">
//<![CDATA[
const fast_path_style = document.createElement('style');
fast_path_style.innerHTML = `#article-body .fastpath{font-size:.9em;background-color:#f3f3f3;border:1px solid #d3d3d3;padding:10px 10px 8px;margin-bottom:16px}#article-body .fastpath::before{content:none!important}`;
document.head.appendChild(fast_path_style);
//]]>
</script><script id="ai-summary-script">
//<![CDATA[
const ai_summary_style = document.createElement('style');
ai_summary_style.innerHTML = `#styled-article-body{padding:0 0 0}#article-body #docs-ai-summary{background-color:#f3f3f3;border:1px solid #d3d3d3;padding:10px 10px 6px;margin-bottom:16px}#article-body #docs-ai-summary #docs-ai-summary-toggle{font-size:.9em;font-weight:700;margin-bottom:4px;cursor:pointer;display:flex;justify-content:space-between;align-items:center}#article-body #docs-ai-summary #docs-ai-summary-toggle #up-triangle{margin-left:auto;padding-right:10px;display:none}#article-body #docs-ai-summary #docs-ai-summary-toggle #down-triangle{margin-left:auto;padding-right:10px}#article-body #docs-ai-summary #docs-ai-summary-content{font-size:.9em;padding-left:25px;padding-right:25px;margin-bottom:12px}`;
document.head.appendChild(ai_summary_style);

const toggleAISummary = () => {
const summary = document.getElementById("docs-ai-summary-content");
const upTriangle = document.getElementById("up-triangle");
const downTriangle = document.getElementById("down-triangle");
if (summary.style.display === "none") {
summary.style.display = "block";
upTriangle.style.display = "none";
downTriangle.style.display = "inline";
} else {
summary.style.display = "none";
upTriangle.style.display = "inline";
downTriangle.style.display = "none";
}
};

document.getElementById("docs-ai-summary-toggle").addEventListener("click", toggleAISummary);
//]]>
</script>
</body>