Tenant Vanity Domains

A vanity domain is a hostname that belongs to one of your tenants, such as surveys.example.com for a customer named Example Corp. With vanity domains, Descope authentication runs on that tenant's hostname. The login screens, session cookies, passkeys, and redirects all stay on surveys.example.com, and your tenant never adds a DNS record that points to Descope.

This page is for B2B applications that already serve each tenant on its own hostname through an edge proxy such as Akamai or Cloudflare. If you want Descope on a single hostname that you own, such as auth.app.example.com, see Custom Domain instead.

Why vanity domains use a reverse proxy

A custom domain works through a CNAME record that points your hostname at Descope. That model fits one hostname per project. It doesn't fit a B2B application that serves hundreds of tenants, because each tenant would need to change its own DNS, and many tenants can't or won't do that.

Vanity domains reuse the routing that you already run. Your edge proxy already receives traffic for every tenant hostname. You add one route that forwards /auth/* on each vanity domain to your project's Descope custom domain. The proxy tells Descope which hostname the user is actually on and what the user's IP address is. The proxy also sends a shared secret that proves the request came from your proxy and not from a client that forged the headers.

Descope then treats the request as if it arrived on the vanity domain. Descope also binds the vanity domain to one tenant, so a request on surveys.example.com can only sign users into Example Corp.

How a request flows

When a user signs in on a vanity domain, the browser talks only to that hostname. Your proxy adds three headers and forwards the request to Descope.

Responsibilities

The setup splits work between your team and Descope. Your team owns everything at the edge, and Descope owns the validation that happens after the request arrives.

Prerequisites

Vanity domains forward traffic to your project's Descope custom domain, so you need a working custom domain first. You also need a management key to call the Management API.

Set up vanity domains

The setup has four parts. You set the proxy secret once per project. You then configure the proxy route, bind each vanity domain to its tenant, and point the frontend SDK at the vanity domain.

curl -X POST "https://<your Descope custom domain>/v1/mgmt/project/settings" \
  -H "Authorization: Bearer <ProjectID>:<ManagementKey>" \
  -H "Content-Type: application/json" \
  -d '{"trustedProxySecret": "<the secret>"}'

curl -X POST "https://<your Descope custom domain>/v1/mgmt/tenant/create" \
  -H "Authorization: Bearer <ProjectID>:<ManagementKey>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Example Corp",
    "id": "example-corp",
    "approvedDomains": ["surveys.example.com"]
  }'

<AuthProvider projectId="<ProjectID>" baseUrl="https://surveys.example.com/auth">

How Descope enforces the tenant binding

The tenant binding is what keeps one tenant's vanity domain from signing users into another tenant. Descope resolves the forwarded hostname to its tenant and validates every tenant-related request against that tenant.

• Flows: A flow that starts on surveys.example.com always signs users into that hostname's tenant.
• Session endpoints: The tenant in a session token must match the hostname's tenant.
• Unbound hostnames: Descope rejects requests from a hostname that isn't bound to any tenant.
• Management API: Calls with a management key run server-side, so Descope doesn't limit them to the vanity domain's tenant. A call that takes a tenant ID still acts on that tenant only. You should call the Management API on your Descope custom domain, not through a vanity domain.

Behavior on vanity domains

A few Descope behaviors change when a request arrives on a vanity domain.

• Cookies: If your project returns tokens in cookies, Descope sets them with Domain=<vanity hostname>. The browser also sends those cookies to the hostname's subdomains. The project's cookie domain setting doesn't apply on vanity domains. If your project returns tokens in the response body, the SDK stores them as usual.
• Passkeys: A passkey that a user creates on surveys.example.com belongs to that hostname and works only there.
• Redirects: Descope allows redirects back to https://<vanity domain>/... for magic links, social login returns, and logout.
• User IP: Descope uses x-descope-forwarded-ip only when the request has a valid proxy secret. If the secret is missing or wrong, or the value isn't a single valid IP, Descope sees your proxy's IP.

Current limitations

Some parts of authentication still run on your Descope custom domain rather than on the vanity domain.

• Social login and SSO: The provider callback lands on your Descope custom domain, and Descope then returns the user to the vanity domain. The provider's consent screen shows your Descope custom domain.
• SAML: The service provider ACS and metadata URLs are on your Descope custom domain, not on the vanity domain.
• OIDC issuer: Descope issues tokens from your Descope custom domain, and serves discovery and JWKS there too.
• Location and network signals: Country, city, ASN, and bot signals still describe your proxy's edge location, not the user's location.
• Secret rotation: A project holds one proxy secret at a time. While Descope and the proxy hold different secrets, Descope ignores the forwarded headers, so requests from vanity domains fail until both sides match.
• Sub-tenants: You bind a vanity domain to a tenant. Sub-tenants don't get their own vanity domain.

Next steps

Once the first vanity domain works, you can bind more tenants through the same Management API calls. To manage the tenants themselves, see Tenant Management. For the cookie settings that apply on your Descope custom domain, see Custom Domain.