Domains & SSO

Miqro runs many domains off one backend, and one sign-on across all of them. This page explains the domain model and exactly how single sign-on works — including the cross-domain handoff that trips people up.

The one principle

A website and a dashboard are two different products for two different audiences. They are never the same host.

Host roles

There are exactly three roles — nothing else is invented:

miqromanage.app — the application

One app. What you see is decided by who you are (profile.tenant_id), not by the URL:

• An operator logs in → the whole fleet (every business, every agent).
• A customer logs in → only their own business.

<customer>.miqromanage.app is an optional vanity host for that customer's dashboard; design.miqromanage.app is the first one. There is no app. subdomain — the app is miqromanage.app.

Single sign-on

Browsers isolate the session cookie per registrable domain. The model follows from that one fact:

• Login lives on one host under .miqromanage.app. The session cookie is Domain=.miqromanage.app, so it is shared by every *.miqromanage.app dashboard automatically.
• The marketing .com sites are public and never authenticate. Their "Sign in" deep-links to the one login.

miqromanage.app/auth/login is the central sign-in wall for both miqromanage customers and the miqrodesign.com storefront.

The cross-domain handoff

This is the subtle part. The login wall's forward() is domain-aware:

• .miqromanage.app family — the shared cookie already covers every subdomain, so the wall redirects back with no token in the URL.
• A different registrable domain (e.g. miqrodesign.com) — it physically cannot read the .miqromanage.app cookie. So the wall hands the session back in the URL fragment (#access_token=…&refresh_token=…), and the receiving site adopts it locally.

That URL-fragment forward is required for cross-registrable-domain SSO; it is not optional sugar. Removing it for .com produces an infinite "can't sign in" loop.

Sign-out

True single sign-out sweeps every Miqro-owned property in turn, clearing each one's local session. The sweep is allowlisted to Miqro hosts only (*.miqromanage.app, *.miqromanage.com, *.miqrodesign.com) to prevent open-redirect and logout-CSRF.

How it scales

• New product → newthing.miqromanage.app. SSO, session, identity: free.
• New customer → a tenant + optional <name>.miqromanage.app dashboard; their public website is on their own domain.
• New marketing domain → public-only; its "Sign in" bounces to the one login.

Invariant: authenticated things are subdomains of the one backbone; public websites are their own domains; nothing authenticates on two registrable domains at once.

Reserved subdomains

Because tenants get <slug>.miqromanage.app, a set of labels is reserved so a tenant can never collide with — or hijack — an infrastructure or product host (app, auth, login, api, support, developers, …). The guard runs at tenant-creation time and in the provisioner's slug-uniqueness check.