Hosted portal on your own domain

By default the hosted portal is served on your Torii host, e.g. your-app-name.shrines.dev. That works, and for sandbox it is all you need. For production you want it on shrines.yourdomain.com instead, which takes one DNS record.

Why it matters

A session is a cookie, and a cookie belongs to a domain.

• Served on your-app-name.shrines.dev, the portal’s session cookie belongs to shrines.dev. Your app on app.yourdomain.com cannot read it. Users sign in successfully and arrive back at your app signed out. In sandbox, Torii works around this by carrying the session in the URL fragment — a development convenience, not something to run in production.
• Served on shrines.yourdomain.com, the cookie is scoped to yourdomain.com, so app.yourdomain.com, dashboard.yourdomain.com and every other subdomain read it directly. No handoff, no fragment, no workaround.

That is the whole reason the dedicated host exists. It is a subdomain of your domain that Torii serves.

Prerequisite

Your custom domain must already be verified — the portal host is derived from it. Set it up under Settings → Domains first; it is also required for production in its own right. With yourdomain.com as your application domain, Torii serves the Frontend API on torii.yourdomain.com and the portal on shrines.yourdomain.com.

Until the custom domain is verified, Project → Shrines → Overview shows no Portal domain section — there is nothing to point at yet.

Set it up

1. Add the CNAME

   In your DNS provider, add a record for the portal host:

   Record	Type	Target
   shrines.yourdomain.com	CNAME	shrines.torii.services

   Copy the exact target from Project → Shrines → Overview → Portal domain rather than typing it — it is shown there with a copy button.

   DNS-only, not proxied

   If your DNS sits behind a CDN with a proxy toggle (Cloudflare’s orange cloud, for example), leave this record DNS-only / grey-clouded. A proxied record breaks certificate validation, and the failure looks like a stuck verification rather than a DNS problem.

   Also check for a CAA record on your apex. One that does not permit Let’s Encrypt or Google Trust Services will stall issuance now and renewals later.

   This is a separate record from the torii.yourdomain.com one your Frontend API uses, and it has a different target. Adding one does not cover the other.

2. Verify it

   In Project → Shrines → Overview → Portal domain, press Verify. Torii registers the host with its certificate authority and checks whether the certificate is active.

   DNS and certificate issuance are not instant. If it reports that the certificate is still being issued, confirm the CNAME resolves and press Verify again in a few minutes — nothing is lost by retrying, and repeat attempts do not create duplicate registrations.

3. Confirm what changed

   Once the badge reads Verified, the three URLs in Portal URLs switch from your Torii host to shrines.yourdomain.com. Update whatever links to them.

   Verifying also widens your session cookie to yourdomain.com, which is what makes the session readable across your subdomains. Torii does this on the verify step rather than making you find a second toggle: the portal is not useful without it. You can review it under Settings → Domains.

Check the thing that actually matters

Certificates and 200s are easy to confirm and are not the point. The assertion worth making is that the session survives the trip back to your app:

1. Sign in at https://shrines.yourdomain.com/sign-in. Do it twice — once with a password, once with an OAuth provider — since they complete over different paths.

2. Confirm you land on your configured redirect target, not back on the portal.

3. Open your app on a different subdomain (app.yourdomain.com) and confirm it sees you as signed in.

4. Inspect the session cookie in your browser’s dev tools. Its Domain must be yourdomain.com, not shrines.yourdomain.com. If it is the latter, step 3 will fail and users will be handed back logged out.

If verification will not complete

In order of likelihood:

• The CNAME is proxied. Set it to DNS-only.
• The CNAME has not propagated. Check with dig shrines.yourdomain.com CNAME before retrying.
• The target is wrong. shrines.torii.services is not the same as the Frontend API target; copy it from the dashboard.
• A CAA record is blocking issuance. Check your apex.

If all four look right and it still will not verify, email [email protected] — we can see the certificate’s status directly.

Turning it back

Removing the custom domain releases the portal host along with the Frontend API host, and the portal returns to being served on your Torii host. Nothing about your users or sessions is destroyed, though anyone holding a session cookie scoped to your domain will need to sign in again.