What domain do I use when setting up OAuth for Zendesk?

Jan 28, 2021

Global OAuth apps need the user's subdomain to work with Zendesk

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 wherever 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 ask the user for their 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 user subdomain collection after Zendesk's login process pictured here:

Screenshot of Zendesk collecting the user's subdomain Zendesk's own subdomain collection screen

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.

Screenshot of Xkit's Zendesk subdomain collection screen Xkit's Zendesk subdomain collection popup

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.

Building CRM integrations?

Xkit delivers deep integrations for every CRM with one build.

Get access ▶