Requesting a global OAuth client for a Zendesk Support integration

If you're developing an integration for Zendesk Support, you can use OAuth authentication to let users grant access to Zendesk Support to your integration. If the integration is for only one Zendesk Support instance, you can create a single, subdomain-specific OAuth client in your Zendesk Support instance. This approach is described in Using OAuth authentication with your application.

However, the setup isn't as simple if you're developing an integration for more than one Zendesk Support instance. You'd have to ask a Zendesk Support admin in each instance to create an OAuth client to connect to your service. They'd also have to provide you with their client ids and secrets. Your app would then have to manage the ids and secrets to request access tokens from the correct Zendesk Support instances.

Fortunately, you can request a global OAuth client from Zendesk Support. A global OAuth client is a secure, cleaner way of using OAuth authentication with multiple Zendesk Support instances. The admins in each instance don't have to set up any OAuth clients.

For security reasons, the global OAuth client will not work with the password grant flow.

Do I need a global OAuth client?

Let's say you develop an internal app that pulls data from your company's Zendesk Support instance. Using a local OAuth client is an efficient solution because a Zendesk Support admin -- yourself or maybe a colleague -- can easily create the client in Zendesk Support.

Now suppose you work for a company that makes a CRM integration for multiple customers with their own Zendesk Support instances. You'd prefer not to ask your customers to manually create local OAuth clients in their Zendesk Support instances just to use your product. A global OAuth client is the solution.

Requesting a global OAuth client

1. Develop your app using a local OAuth client in your Zendesk account. Ensure your Unique Identifier is prefixed with the string "zdg-". For example, "zdg-global-unique-identifier".

2. After the app is finished and ready to use across multiple Zendesk Support accounts, submit your request as described below.

   Note: Make sure you note down the secret and the identifier before making your request. Otherwise you'll lose access to the client administration page after the local client is converted.

3. Sign in to the Zendesk Developers portal and then select My Account from the menu on the upper-right side.

4. Click OAuth Client Globalization in the left navbar, then complete the request form.

   

If the request is approved, we'll convert your local OAuth client to a global OAuth client.

If your request is rejected for whatever reason, you can still implement OAuth in your integration using a local OAuth client. You'll need to have each of your customers create a local OAuth client and provide information about the OAuth client before they can connect your service to their Zendesk Support instance.

Frequently asked questions

Why do you need my subdomain even with a global client?

Unlike services like Twitter or Facebook that behave as global authentication systems, Zendesk maintains separate logins for each Zendesk Support account or subdomain. When a customer signs in, they're signing into a specific Zendesk Support subdomain. That carries over to OAuth. When a Zendesk Support account owner uses OAuth to authorize your service, they're authorizing the service for their subdomain. So we need to know the subdomain.

Prompting the user for their Zendesk Support subdomain can still be beautifully simple:

Why can't I edit my global client?

We must take control of the client to make it global. It can only be edited by our Platform Team. If you're having trouble with your global client, contact us for assistance.

Join the discussion about this article in the community.