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

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

TL;DR

  • You need to use the end user’s subdomain when building your Zendesk app
  • The end user needs to provide their subdomain before sending them through the auth flow

Stop wasting time on auth and instead use Xkit’s free, preconfigured auth service which manages, stores, and encrypts tokens for you. Focus on the differentiated parts of your product and let us handle the auth.

Sections

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:

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.

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.

Become an integrations expert.

Stay up to date on the latest articles about native integrations, new
Xkit features, and more by signing up for our mailing list.

Why does my GitHub OAuth2 Token not have the scopes I requested?