> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pylonsync.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Customer domains

> Serve each of your customers on their own domain from one app: attach the domain with ctx.domains, pick the tenant from props.host, and let users sign in on that domain.

A platform app serves many customers. Each customer can have their own domain,
such as `feedback.acme.com`, that points at your app. Pylon Cloud issues the
certificate, and your app decides what to render from the host of the request.

This page covers three parts:

1. Attach the domain with `ctx.domains`.
2. Pick the customer from `props.host` in a page.
3. Sign users in on the customer's domain.

`ctx.domains` works on Pylon Cloud only. On a self-hosted server every method
throws `DOMAINS_NOT_CONFIGURED`.

## Attach a domain

Call `ctx.domains.add` from an action when your customer enters their domain.
The result has the DNS records the customer must add.

```ts theme={null}
import { action, v } from "@pylonsync/functions";

export default action({
  args: { hostname: v.string() },
  async handler(ctx, args) {
    const d = await ctx.domains.add(args.hostname);
    // Show the customer every record in d.records:
    //   { type: "CNAME" | "A" | "AAAA" | "TXT", name, value, purpose }
    return d;
  },
});
```

Both subdomains (`sell.acme.com`) and apex domains (`acme.com`) work:

* A subdomain gets a `CNAME` to `d.cnameTarget`, plus `TXT` records for
  ownership and the certificate.
* An apex cannot be a CNAME, so `d.apex` is `true` and the customer adds
  `A` and `AAAA` records pointing at your app. `d.cnameTarget` is `null`.
  The certificate is requested on the first `status()` call after those
  records point only at your app; until then `status()` lists the DNS
  problem in `errors`. A project can have 25 apex domains waiting for DNS
  at once.

Then poll `ctx.domains.status(hostname)`. When `status` is `"ready"`, the
certificate is active and your app accepts requests for the host. Pylon
refreshes the list of ready hosts every 30 seconds, so there is no deploy per
domain. `ctx.domains.remove(hostname)` detaches a domain.

Keep your own record of which customer owns which hostname. The control plane
only knows that the hostname belongs to your app.

## Pick the customer from the host

Every page gets `props.host`. It is the request's host, lowercased, when the
server trusts it, and `""` otherwise. A ready customer domain is trusted.

```tsx theme={null}
import { use } from "react";
import type { PageProps } from "@pylonsync/react";

export default function Home({ host, serverData }: PageProps) {
  // Your own lookup: which customer owns this hostname, if any.
  const tenant = use(serverData.fn<Tenant | null>("tenantForHost", { host }));
  if (!tenant) return <MarketingHome />;
  return <TenantHome tenant={tenant} />;
}
```

Rules that hold for `props.host`:

* A forged `Host` header gives `""`. A page cannot be made to render another
  customer's content by a header the server does not trust.
* `host` is part of the SSR cache key. Each host gets its own cache entry, so
  a page with `export const revalidate` stays cacheable.
* The browser receives the same value in the hydration payload.

Links inside a customer's site must stay on that host. Use root-relative paths
(`/roadmap`), not paths with your app's own prefix.

## Sign users in on the customer's domain

A session cookie belongs to one host. Pylon sets it on the host that asked for
it:

* **Email and password, magic codes, passkeys.** These run on the customer's
  domain directly. The session cookie is host-only on that domain, also when
  `PYLON_COOKIE_DOMAIN` is set for your own domain, because a browser drops a
  cookie whose `Domain=` does not cover the host.
* **OAuth (Google, GitHub, and others).** The provider only knows your app's
  one registered callback URL, on your own host. Pylon moves the sign-in to
  the customer's domain with a one-time code.

To start an OAuth sign-in on a customer's domain, request the login URL from
that domain, with an absolute callback on the same domain:

```ts theme={null}
const callback = `https://${location.host}/`;
const res = await fetch(
  `/api/auth/login/google?callback=${encodeURIComponent(callback)}`,
);
const { redirect } = await res.json();
location.href = redirect;
```

What happens next:

1. The start request sets a short-lived, host-only cookie on the customer's
   domain. It binds the sign-in to this browser.
2. The provider returns the browser to your app's callback. The callback does
   not set a session cookie on your host. It redirects to
   `https://<customer domain>/api/auth/handoff?code=…`.
3. The handoff request, on the customer's domain, checks the code and the
   binding cookie, creates the session, sets the cookie, and redirects to the
   callback URL.

The handoff code:

* is 32 random bytes, and only its SHA-256 is stored,
* works once, for 120 seconds,
* works only on the domain it was made for,
* works only in the browser that started the sign-in, so a code sent to
  another person cannot sign them in to the sender's account.

A sign-in that returns to a customer's domain must start on that domain. A
start request on another host gets `400 HANDOFF_WRONG_START_HOST`.

The handoff errors are:

| Status | Code | Meaning |
| - | - | - |
| 400 | `HANDOFF_INVALID` | The code expired or was used. Sign in again. |
| 400 | `HANDOFF_WRONG_HOST` | The code was made for a different domain. |
| 403 | `HANDOFF_OTHER_BROWSER` | The browser does not have the binding cookie. |
| 403 | `HANDOFF_HOST_NOT_TRUSTED` | The domain was detached after the sign-in started. |

The handoff codes are stored with the other auth state (SQLite or Postgres), so
a sign-in that starts on one machine can finish on another.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.