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
-
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".
-
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.
-
Sign in to the Zendesk Developers portal and then select My Account from the menu on the upper-right side.
-
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.
19 Comments
Hi Sean,
Thanks for your article. I have been reading it in conjunction with the Authorization Code Grant flow example urls in https://support.zendesk.com/entries/24458591-Using-OAuth-authentication-with-your-application
For Global OAuth clients, using Authorization code grant flow, please can you clarify whose responsibility it is to prompt for the zendesk subdomain? Your article includes an example prompt UI; so is the intention that our client application should capture this subdomain value first and pass this through as an extra parameter on the call to the Zendesk authorization page : eg
https://{our-global-client-subdomain}.zendesk.com/oauth/authorizations/new?response\_type=code&redirect\_uri={our\_redirect\_url}&client\_id={our\_unique\_identifier}&scope=read%20write**&subdomain={****the-customers-subdomain}**
If so what is the form of this extra parameter?
Alternatively, does your Authorization page prompt for the subdomain itself ?
If so, do you pass the user's chosen value back as an additional parameter on the registered redirect url : eg
{our\_redirect\_url}?code=7xqwtlf3rrdj8uyeb1yf**&subdomain={chosen-subdomain}**
So that our generic receiving servlet url knows which subdomain the code is for.
Many thanks
Simon Pledger
**@Simon:** It is your responsibility to prompt for subdomain in your code. When it comes to the authorization workflow, the customer's subdomain is what's actually used to construct the URL not the ID of your global client. Your global OAuth client does not have its own subdomain. For example, if your customer's subdomain were omegasupport.zendesk.com then the URL would look like this:
https://omegasupport.zendesk.com/oauth/authorizations/new?response\_type=code&redirect\_uri={our\_redirect\_url}&client\_id={our\_unique\_identifier}&scope=read%20write
It is the client\_id parameter that tells us to use your specific global OAuth client.
Hi Sean
I understand; thanks for the clarification.
I'm thinking therefore that if we also add the captured subdomain to our session before redirecting the user to the authorization endpoint, our global client's redirect url endpoint can use this same session attribute to associate any returned authorization code parameter with its correct subdomain. Is this how you envisaged a global client based authorization workflow proceeding?
Regards
Simon
**@Simon:** Subdomain is required any time you or an end-user of your integration interacts with Zendesk's OAuth endpoints. You thus need to make sure you're tracking subdomain associated with each authorized user. This is especially important because any subsequent API operations will also require the customer's subdomain. You're always acting on behalf of a user in a specific Zendesk subdomain regardless of whether a global OAuth client is used.
Hi,
Can global clients (using the auth code grant type) get refresh tokens or, failing that, non-expiring access tokens? I need that for my integration which is expected to be acting on the user's behalf without their continuous UI presence.
Thanks
Rather than pushing the complexity of prompting for the subdomain to the client, Zendesk could have a global entry point on zendesk.com that would provide a consistent interface for prompting for the subdomain, and could also look at cookies to see what subdomain the user was in previously so that it can be autofileld as most users only use one domain.
btw: just because there are a number of flows in OAuth 2, does not mean you need to support them all.
@Sean,
Does it mean that only the need of asking the consumer id and secret to the every zendesk account admin is eliminated but for rest like getting access and renew tokens are bound to the chosen subdomain of zendesk and that is something our app needs to maintain ?
Also, is there a way that global OAuth client is given for trial accounts so that we could do a POC to ensure the suitability.
Sean,
I had a question about the "Proof of Business" requirement. We are a small startup and have not yet incorporated. We do have a webpage through which our web app can be accessed; our apps are also available on Google Play and Apple Store.
How can our app integrate with Zendesk in a global production capacity without any "Proof of Business" documentation? We have already tested our app with our own subdomain and would now like to open it up for global users to use.
Out app is an enterprise search app called Hadro (http://www.hadroapp.com).
Thanks.
How many ideally will it take for the Global OAuth Client request to get approved ? And do we have any contact person (admin from Zendesk) to get directly in touch with? And is it possible to edit the submission request done previously ? Looking forward for some urgent help here! We are building base integration with multiple apps. Thanks. deepakteja[at]pipemonk.com
Hi Deepak,
You can request a Global Oauth Client through the developer portal. You'll need to create an account there, and then submit your Zendesk subdomain, unique identifier, and proof of business. Sign up for more information - https://developer.zendesk.com/account/oauth
Lastly, it is not possible to edit the submission.
@James
Firstly, thanks for a quick reply. We have already submitted the request for Global Oauth Client through the portal with all the details.
Now, the following question would be, if it is not possible to edit the submission, should we wait for the Zendesk admin to contact us in response or submit a new request from our end ?
Looking forward. Thanks once again.
Hi Deepak,
I'd suggest waiting for Zendesk to contact you and hopefully you can notify of the change that is required before the client is globalized.
And James, Can there any kind of guess on the time line for this request? Because a lot of other actions at our end depends on this! Tx.
Hi Deepak, Unfortunately that is not something I'm qualified to answer.
@James, No problem. Thanks a lot for the help. I hope the concerned and the right person from Zendesk team, will answer soon!
@Sean @James, I have no luck OAuthorizing any of ZD accounts using my global OAuth credentials.
Authorization page says no such client!
Hi Zendesk Team Zendesk @... After I apply for the global client,How should I use this client to authorize user_domain?
How to pass the parameters of the authorization link, and whether the access domain is the user's domain or the global domain, If it is a global domain, how should the user domain be passed to the authorized link
In addition, how is example_prompt.png triggered, and what are the links before and after the trigger?
Thank you very much!
Hi lemon -- I would check out this article: Creating and using OAuth tokens with the API
Setting up a global OAuth client is needed if you're thinking of developing a Zendesk Marketplace app that is used by different customers who each have their own unique Zendesk Support subdomain.
To answer you're question, it's up to you to request the customer's subdomain. In this workflow, it's your third-party/remote service that wants to access the customer's Zendesk instance. If this is the case in the integration that you're considering to write, it would be this remote service that they would be logged into (some sort of admin portal probably) that then asks for their Zendesk subdomain, that then does the OAuth grant flow steps.
In the end, a "global" OAuth client is just another OAuth client -- the advantage is that you don't have to ask each separate customer to set it up -- it's already set up for them. Meaning that this is really just a convenience feature.
Hi,
I successfully submitted the request for a global OAuth client in the Zendesk developers portal, but did not get any email notification regarding this. Can I check the status of it somewhere?
Can I submit separate requests for global OAuth clients for multiple local OAuth clients in my Zendesk account?
Also, is there a rough timeline on when the request for global OAuth will be approved ?
Any information in this regards would be appreciated.
@...
Thanks in advance !
Please sign in to leave a comment.