Using the Conversations API keys

When making requests using Sunshine Conversations APIs, authentication is required to verify the caller's identity. You can use either Basic authentication or JSON 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.

Note: The API key described here is different from the Integrating conversations in Admin Center 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.

Access to the Conversations API page is included in the Zendesk Suite Professional plans or above. You must have the Zendesk Agent Workspace activated to see the page. Additional add-on packs are available if you require more Monthly Active Users (MAU) or notifications. For more information, see About Zendesk Suite add-ons.

This article includes these sections:

• About API keys
• Creating and sharing the IDs and API key

About API keys

An API key identifies and authenticates an application or user and is composed of three pieces:

• The App ID identifies your Zendesk account.
• The Key ID when used together with the secret key are the credentials used to authenticate JWTs and API calls.
• The secret key is the authentication password.

With Basic authentication, you make requests using an API key directly. The key ID is the username and the secret is the password.

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 kid property, while the secret signs the JWT.

API keys are not as secure as authentication tokens. Be sure to follow good practices to securely handle credentials when using an API key in production.

For more information on Sunshine Conversations authentication, see API Authentication.

The Sunshine Conversations API key is different from messaging authentication keys. 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 Sunshine Conversations public APIs that support the app scope.

Creating and sharing the IDs and API key

A Zendesk administrator must create an API key and share it with the developer. You can store up to 10 keys.

To create and share an API key

1. In Admin Center, click Apps and integrations in the sidebar, then select APIs > Conversations API.
   Note: You must have a Zendesk Suite Professional plan or above to view this window.
2. Click Create API key.

   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.

3. Enter an identifying name for the key in the Create new key dialog, then click Next.
4. In the Copy shared secret dialog, click Copy for each ID and secret key to save it to your clipboard, then click Next.

   You're returned to the API window, where the new key appears in the list.

If you generate a new key but have reached your 10-key limit, a notification appears, asking you to delete any unused keys.

To delete an unused key

1. In Admin Center, click Apps and integrations in the sidebar, then select APIs > Conversations API.
2. Hover your mouse pointer over the key you want to delete, then click the options menu () and select Delete.
3. Confirm the action by clicking Delete.