If you're building a Zendesk integration that allows your users to connect their Zendesk accounts to your app, you have probably noticed that all the Zendesk documentation for OAuth use the domain {subdomain}.zendesk.com, and you might be asking: whose subdomain is this? Is it the app developer's or the user's?
The subdomain you use when developing OAuth apps for Zendesk is the user's subdomain
The answer is that it's the user's subdomain, not you, the developer's subdomain. If you're building the integration only for internal use, that's the same subdomain so it won't matter, but if you intend for other Zendesk users to make use of it (what Zendesk calls a "global OAuth client"), you'll need to use their subdomain.
Why do I need the user's subdomain?
Why use the customer's subdomain? Zendesk's docs sum it up:
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.
The documentation can be a little bit confusing at times, using "your" subdomain at times when they mean "the user's" subdomain. Just know whereever you see {subdomain}, they're referring to your user, not you.
How to get the user's subdomain
Now you might be wondering if Zendesk provides a sort of global subdomain that you can use where Zendesk either determines through cookies, or collects directly from the user, their Zendesk subdomain. The unfortunate answer here is no: you're left to your own devices to determine the user's subdomain before sending them through the OAuth flow. You'll also need to hang on to this subdomain: it's used not only for the initial authorization request, but also the token request and API calls afterward.
You'll probably want to model your own subdomain collection after Zendesk's login process pictured here:
Conclusion
So if you're building a Zendesk integration, don't forget to build in subdomain collection to make sure you're making requests to the right domain.
Of course, if you don't want to bother building an entire subdomain collection flow, you can use Xkit's Zendesk Connector. It has built-in subdomain collection through a popup window and it will surface the subdomain to you with every access token it provides.
With one API call you'll get everything you'll need to get access to your user's Zendesk account. And you can get started in 30 minutes, for free.
Top comments (0)