DocumentationAPI Reference

Set up a global OAuth client

Set up a global OAuth client

If you're developing an integration for Zendesk Support, you can use OAuth authentication to allow your integration to access a user's Zendesk Support account. If the integration is for only one Zendesk instance, you can create a single, subdomain-specific OAuth client in your Zendesk 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 instance. Fortunately, you can request a global OAuth client from Zendesk. A global OAuth client is a secure, cleaner way of using OAuth authentication with multiple Zendesk instances.

Note: For security reasons, Zendesk doesn't allow developers to create their own global OAuth clients.

Do I need a global OAuth client?

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

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

Requesting a global OAuth client

To request a global OAuth client

  1. Develop your app using a local OAuth client in your Zendesk account. For more information, see Using OAuth authentication with your application. Ensure your Unique Identifier is prefixed with the string "zdg-". For example, "zdg-global-unique-identifier". Make sure all fields are filled out on the local client (even the one's labeled "optional") as they are required for global clients.

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

    Note: Make sure you note down the secret and the identifier before making your request. You will lose access to the client administration page after the local client is converted to a global client.

  3. Sign in to the Zendesk Marketplace portal, and select Organization from the menu on the left side. Then navigate to the Global OAuth Request tab.

  4. Complete the request form. Ensure the subdomain includes the prefix "d3v-". We will not accept submissions from non-d3v- accounts. Note: The "d3v-" and the "zdg-" are prefilled in the form. Make sure the values are properly created on the local OAuth client in your sponsored account and that your sponsored account has the proper account prefix as well.

    To request a sponsored developer account, see Getting a trial or sponsored account for development

  5. Done! You'll receive an email and a ticket reference with updates on your submission. Please add "[email protected]" to your contact list to ensure you receive e-mail communications from us regarding your submission.

If the request is approved, Zendesk converts your local OAuth client to a global OAuth client.

If your request is rejected, you can still implement OAuth in your integration using a local OAuth client. Before your customers can connect your service to their Zendesk Support instance, they will need to each create a local OAuth client and provide information about the OAuth client.

Frequently asked questions

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

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

Why can't I edit my global client?

Zendesk must take control of the client to make it global. It can only be edited by our Marketplace Operations Team. If you are having trouble with your global client, reach out to Zendesk Support by following the instructions here and using "Option 2". Be sure to mention "global oauth" when you describe your issue to the bot and include the client_id as well as the changes you need made.

Can I use my global OAuth client for my bot?

You will need to request a separate OAuth token when creating a bot. You cannot use a Zendesk Support global OAuth for building a bot using Sunshine Conversations.

Does this global OAuth client work with Zendesk Sell?

No, these instructions only apply for Zendesk Support and Chat (Agent Workspace enabled) accounts. For Zendesk Sell, you will need to register a Multi-User Application as part of the authentication flow.

Next steps: Create assets