Zendesk

📘

Important

This guide is for both Zendesk Support and Zendesk Guide. The setup is the same on Zendesk's site, but you will have to select which of these you are connecting with in Xkit and the scopes and APIs vary between them.

Zendesk's Guide: https://support.zendesk.com/hc/en-us/articles/203663836-Using-OAuth-authentication-with-your-application
Authorization protocol: OAuth 2.0

1. Add the Zendesk connector in the Xkit platform.

• In the Xkit platform, click "New connector" in the sidebar or at the bottom of the "Connectors" screen.
• Click "Zendesk Support" or "Zendesk Guide", depending on which you would like to connect with. At this point you'll see a callback url, which you'll provide to Zendesk in the next step, and places to input the Client ID and Client Secret that you'll get from Zendesk after registering your app with them.

2. Register your application with Zendesk.

• Next, in a separate window, sign in to your Zendesk account or create a free sponsored developer account (details here) if you don't have one.
• Click the gear icon in the sidebar and then "API".
• Click the "OAuth Clients" tab and then the "+" button to create a new OAuth client.
• Submit your Client Name and, optionally, additional general information like your logo and app description.
• Copy/paste the "Unique identifier" into the Client ID field on the Xkit page.
• Under "Redirect URLs", copy/paste the callback URL from the Xkit platform.
• Click "Save" and "OK".

3. Provide Xkit with the Secret.

• After completing the last step, you should have been taken to a screen that shows your Secret at the bottom.
• Copy/paste the Secret into the Client Secret field on the Xkit page.

4. Submit an OAuth Client Globalization request.

• Unless your integration is only for one Zendesk instance, you will need to submit a request for OAuth Client Globalization (additional info can be found here).
• To do this, visit https://developer.zendesk.com, click your account name at the top right and then "My Account".
• Next, in the sidebar, click "OAuth Client Globalization".
• Fill out the requested general information and click "Submit".

5. Complete the Xkit connection setup.

• Now that you've provided the callback URL to Zendesk and entered the Unique Identifier and Secret into the Xkit platform, click "Save" on the Xkit page.
• Fill out the Catalog Settings page and again click "Save".
• On the next page, select the permissions/scopes your application requires and click "Save" (additional details about the scopes are available here).

You've now successfully connected Zendesk with Xkit!

Calling Zendesk APIs

Zendesk's APIs are segregated by customer: each customer has their own unique subdomain. Xkit's authentication is through a specific customer subdomain, and developer API calls must be made to the customer's subdomain as well.

Xkit collects this subdomain from the end user and exposes it to the developer through the Get User Connection and Get Group Connection endpoints, in the authorization.zendesk_subdomain property. Your application should use this zendesk_subdomain when calling Zendesk APIs.