Passkey well-known use cases

Two jobs teams actually hit: squeezing multi-brand origins under the common 5-label related-origins cap, and shipping related origins before enroll/manage deep links are ready.

1. Multi-brand + rewards domain under the 5-label cap

Who: A product with example.com, example.co.uk, example.de, and a separate rewards property example-rewards.com. Federation is not practical yet; you want one passkey RP ID.

Task: Publish related origins (and preferably passkey-endpoints) on the RP ID domain without exceeding the label budget browsers commonly enforce.

  1. Set RP ID to example.com — both well-known files live on that domain.
  2. List only the extra https origins that must share passkeys. Treat example and example-rewards as different registrable labels; country TLDs still consume budget.
  3. Open the generator. Watch the label counter. If it warns above five distinct labels, drop a low-traffic origin or postpone it — the warning is advisory relative to common browser caps, not a full Public Suffix List oracle.
  4. Add enroll/manage URLs on the primary account area for passkey-endpoints.
  5. Deploy both extensionless files on https://example.com/.well-known/ with Content-Type: application/json using the Pages recipe (or Nginx default_type).
  6. Point every related origin’s WebAuthn calls at the same rpId.

Result: Users who registered on example.com can use the same passkey on listed brand domains. Password managers can deep-link into enroll/manage when endpoints are present.

Failure mode: Serving HTML, redirecting the well-known paths, or silently omitting a brand from the list while still calling that RP ID from the omitted origin.

2. Progressive rollout: related origins first, endpoints later

Who: A team that already needs Related Origin Requests this sprint, but the polished account “create / manage passkeys” URLs are still behind a redesign.

Task: Ship a correct webauthn related-origins document now; add passkey-endpoints when the UX is ready — without confusing “optional endpoints” with “optional related origins.”

  1. Uncheck “Also generate passkey-endpoints” in the tool (or leave enroll/manage empty and omit that file from deploy).
  2. Deploy only /.well-known/webauthn with JSON Content-Type on the RP ID domain. Verify with curl that you get 200 + JSON, not a SPA shell.
  3. When account URLs exist, regenerate the pack with enroll/manage filled, deploy /.well-known/passkey-endpoints beside the first file, and keep both Content-Type rules in _headers.
  4. Do not advertise endpoints that 404. Password managers deep-linking into a broken manage page is worse than shipping related origins alone.
Order of operations: Related origins unlock cross-origin RP ID reuse. Endpoints are discovery for managers. You can ship related origins first; once managers need deep links, both files should live on the same RP ID domain. See FAQ.