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

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.

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.

before:

https://myorgname.clubhouse.io/stories

after:

https://app.clubhouse.io/myorgname/stories

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 *.clubhouse.io.

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.

TL;DR

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.