Skip to main content
Automatically keep your work and documentation completely in sync.LearnaboutDocs.
Example of what can happen while building a web application

Example of what can happen while building a web application

Building a SaaS App? You should probably stick to a single subdomain.

Andrew Childs

Of all of the big architectural decisions we’ve made over the last 2 years building Shortcut, we’re lucky that (so far) only one of those decisions was a mistake worth rewriting a lot of code for: using the subdomain to indicate the current organization. As we’re in the process of backing out of that decision, I’d like to share how we got here, and why we’re making this change now, so hopefully someone else doesn’t make the same mistake.

Why Would You Use Subdomains at All?

Using the subdomain to indicate the current organization is a common pattern, in use by companies such as Slack and Zendesk. If the product allows a user to belong to different organizations, putting the organization in the subdomain is arguably a more explicit way to let the user know where they are. The organization doesn’t pollute the URL pathname. We never actually did this, but we could have started serving individual organizations from different regions at the DNS level. So we thought about the above and said “let’s use subdomains” and that was that.

Contrasting SaaS URL strategies

Why This Was Actually a Bad Idea™

We’re in the process of allowing a single Shortcut user to belong to and quickly switch between multiple organizations, and moving the organization slug to the pathname makes it easy to switch organizations in a local dev environment.

It means we no longer need separate code paths for dev/staging/prod environments when we parse the URL — in fact we no longer need to look at the hostname at all. So the code and the developer experience has been improved.



On top of that, we recently added OAuth support for Google Drive for file attachments (and eventually, as a way to log in using your Google account), however Google requires a domain whitelist for OAuth access, which makes it difficult to use a wildcard domain. Moving to a single subdomain allowed us to rip out a lot of extra code & an extra click to get around that. And as we support more third-party integrations, it’s a safe assumption that this will come up again.

We’ll also be able to get an Extended Validation SSL certificate, which is nice because it provides some extra visual assurance that the certificate is trustworthy. EV SSL certificates can’t be assigned to wildcard addresses like *

Why Put the Organization in the URL at all?

It’s very common to not include the current organization/user in the URL at all. That works fine for products where you don’t have multiple accounts, but if you do, a major drawback is that you are redirected to your last viewed account, not necessarily the account you want to see. There are visual cues you can add to a UI to make it more obvious where you are, but your URL should act as the source of truth about where you are. You should for example be able to use your browser history to navigate to the account you want to see. Rollbar for example gets this, and uses /myCo/myProject/items. Meanwhile, in Google Docs, you’re constantly thrown into the wrong account because the account isn’t transparently represented in the URL.


If you’re building a SaaS app that has any third-party OAuth integrations, or your product allows a user to switch between multiple organizations, you should put the organization in the pathname and use a single subdomain (like “app”) for your application.

More stories from Shortcut