Using Conversations API keys

<body>
<p id="docs-hc-snippet" style="display: none;">When making requests using Sunshine Conversations APIs, authentication is required to verify the caller's identity. You can use eitherBasic authenticationBasic authenticationorJSON Web Tokens (JWTs)to verify a caller's identity. Both methods require an API key. You create the API key using the Conversations API page.</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_pee">
<table>
<tbody>
<tr>
<td>
<strong>All Suites</strong>
</td>
<td>Professional, Enterprise, or Enterprise Plus</td>
</tr>
</tbody>
</table>
</div>

</div>

<div class="body">

<p class="p">When making requests using Sunshine Conversations APIs, authentication is required to
verify the caller's identity. You can use either <a class="xref" href="https://docs.smooch.io/guide/basic-authentication/" target="_blank">Basic authentication</a>
<a class="xref" href="https://docs.smooch.io/guide/basic-authentication/" target="_blank">Basic authentication</a> or <a class="xref" href="https://docs.smooch.io/guide/jwt/" target="_blank">JSON Web
Tokens (JWTs)</a> to verify a caller's identity. Both methods require an API key.
You create the API key using the Conversations API page.</p>
<div class="p">
<div class="note" id="using_the_conversations_dashboard__note_gsk_cqy_wwb">
<span class="notetitle">Note:</span> The API key described here is different from the <a class="xref" href="https://support.zendesk.com/hc/en-us/articles/4576083789850" target="_blank">Integrating conversations in Admin Center</a> API key. The
conversations API key described here is intended for app-level authentication. The
integrating conversations API key is specific to a conversation integration.</div>
</div>
<p class="p">Access to the Conversations API page is included in the <a class="xref" href="https://support.zendesk.com/hc/en-us/articles/4408846875034" target="_blank">Zendesk Suite Professional plans or above</a>. You must have the
Zendesk Agent Workspace <a class="xref" href="https://support.zendesk.com/hc/en-us/articles/4581758611866" target="_blank">activated</a> to see the page. Additional add-on packs are
available if you require more Monthly Active Users (MAU) or notifications. For more
information, see <a class="xref" href="https://support.zendesk.com/hc/en-us/articles/4408834152730" target="_blank">About Zendesk Suite add-ons</a>.</p>
<p class="p">This article includes these sections:</p>
<ul class="ul" id="using_the_conversations_dashboard__ul_tbm_dgr_ktb">
<li class="li"><a class="xref" href="#topic_qvw_5fr_ktb">About API keys</a></li>
<li class="li"><a class="xref" href="#topic_o5g_3h5_2tb">Creating and sharing the IDs and API
key</a></li>
</ul>
</div>
<div aria-labelledby="ariaid-title2" class="topic nested1" id="topic_qvw_5fr_ktb">
<h2 class="title topictitle2" id="ariaid-title2">About API keys</h2>
<div class="body">
<p class="p">An API key identifies and authenticates an application or user and is composed of
three pieces:</p>
<ul class="ul" id="topic_qvw_5fr_ktb__ul_nrf_yfr_ktb">
<li class="li">The <strong class="ph b">App ID</strong> identifies your Zendesk account.</li>
<li class="li">The <strong class="ph b">Key ID</strong> when used together with the secret key are the credentials
used to authenticate JWTs and API calls.</li>
<li class="li">The <strong class="ph b">secret key</strong> is the authentication password.</li>
</ul>
<p class="p">With Basic authentication, you make requests using an API key directly. The
key ID is the username and the secret is the password. </p>
<p class="p">With JWTs, you sign tokens with an API key, which are then used to
authenticate with the API. The key ID is included in the JWT header as the
<code class="ph codeph">kid</code> property, while the secret signs the JWT.</p>
<p class="p">API keys are not as secure as authentication tokens. Be sure to follow good
practices to <a class="xref" href="https://docs.smooch.io/guide/authentication-secure-credential-handling/" target="_blank">securely handle credentials</a> when
using an API key in production.</p>
<p class="p">For more information on Sunshine Conversations authentication, see <a class="xref" href="https://docs.smooch.io/guide/authentication-overview/" target="_blank">API Authentication</a>.</p>
<p class="p">The Sunshine Conversations API key is different from <a class="xref" href="https://support.zendesk.com/hc/en-us/articles/4411666638746" target="_blank">messaging authentication keys</a>. Messaging authentication
keys are used to sign credentials that authenticate end users using Zendesk SDKs.
The API key here is for server-to-server calls and provides access to <a class="xref" href="https://docs.smooch.io/rest/" target="_blank">Sunshine
Conversations public APIs</a> that support the <code class="ph codeph">app</code>
scope.</p>
</div>
</div>
<div aria-labelledby="ariaid-title3" class="topic nested1" id="topic_o5g_3h5_2tb">
<h2 class="title topictitle2" id="ariaid-title3">Creating and sharing the IDs and API key</h2>
<div class="body">
<p class="p">A Zendesk admin or agent with permission to manage APIs can create an API key and
share it with the developer. You can store up to 10 keys.</p>
<p class="p"><strong class="ph b">To create and share an API key</strong></p>
<div class="p">
<ol class="ol" id="topic_o5g_3h5_2tb__ol_zcc_ph5_2tb">
<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_o5g_3h5_2tb__image_skw_1sl_gtb" 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">APIs &gt; Conversations
API</strong>.</span><div class="p">
<div class="note" id="topic_o5g_3h5_2tb__note_zdx_nls_g5b">
<span class="notetitle">Note:</span> You must have a <a class="xref" href="https://support.zendesk.com/hc/en-us/articles/4408846875034" target="_blank">Zendesk Suite Professional plan
or above</a> to view this window.</div>
</div>
</li>
<li class="li">Click <strong class="ph b">Create API key</strong>. <p class="p">If you are creating your first key, this
button appears at the bottom of the page; if you have previously created
a key, it appears in the top-right corner.</p>
</li>
<li class="li">Enter an identifying name for the key in the Create new key dialog, then
click <strong class="ph b">Next</strong>.</li>
<li class="li">In the Copy shared secret dialog, click <strong class="ph b">Copy</strong> for each ID and secret
key to save it to your clipboard, then click <strong class="ph b">Next</strong>.<p class="p">You're returned
to the API window, where the new key appears in the list.</p>
</li>
</ol>
</div>
<p class="p">If you generate a new key but have reached your 10-key limit, a notification appears,
asking you to delete any unused keys.</p>
<p class="p"><strong class="ph b">To delete an unused key</strong></p>
<div class="p">
<ol class="ol" id="topic_o5g_3h5_2tb__ol_wtz_kll_gtb">
<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_o5g_3h5_2tb__d9e2363" 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">APIs &gt; Conversations
API</strong>.</span></li>
<li class="li">Hover your mouse pointer over the key you want to delete, then click the
options menu (<img class="image" id="topic_o5g_3h5_2tb__image_mbx_z1c_lmb" src="https://zen-marketing-documentation.s3.amazonaws.com/docs/en/support_trigger_options.png" width="16">) and select <strong class="ph b">Delete</strong>.</li>
<li class="li">Confirm the action by clicking <strong class="ph b">Delete</strong>.</li>
</ol>
</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/4576088682266",
"url": "https://support.zendesk.com/hc/en-us/articles/4576088682266",
"headline": "Using Conversations API keys",
"description": "You can create and manage API keys for authenticating server-to-server requests to Conversations APIs, including generating, sharing, and deleting keys through the Admin Center interface.",
"articleSection": "Extending Zendesk",
"datePublished": "2022-05-03T22:07:46+00:00",
"dateModified": "2026-08-11T20:56:19.804901+00:00",
"inLanguage": "en-US",
"mainEntityOfPage": {
"@type": "WebPage",
"@id": "https://support.zendesk.com/hc/en-us/articles/4576088682266"
},
"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>
</body>