These docs are a work in progress and may not be fully up to date. Some pages may contain internal notes for our team.
Skip to Content
EmbeddingAuthorized URLs (embedding)

Authorized URLs (embedding)

Every Finder has an Authorized URLs list — an allowlist of origins where the widget is allowed to render. The list is your protection against someone copying your embed snippet onto an unauthorized site. This page covers Authorized URLs from the integrator’s perspective: what to add when you start, when to add for new environments, and what happens when an origin isn’t on the list.

For the workspace-owner-side configuration (the same setting from a different angle), see Authorized URLs in customization.

What an authorized URL is

An origin in the web sense: a scheme (https://), a host (www.example.com), and a port (default 443 for HTTPS, 80 for HTTP). Two URLs share an origin if their scheme, host, and port all match.

When the widget loads on a host page, it compares the page’s origin to the Finder’s Authorized URLs list. If the origin is on the list, the widget renders. If not, it doesn’t.

Where to manage the list

In the Finder Builder:

  1. Open the Finder you want to configure
  2. Open the Launch section in the sidebar
  3. The Authorized URLs panel lists every origin you’ve added; the input below adds another

🟡 [SCREENSHOT: Authorized URLs panel in the Finder Builder Launch section showing three production-style origins added and a fourth being typed.]

Click Save when you’re done. Changes take effect within ~5 minutes (CDN propagation; see Caching).

Pattern: starting a new embed

A typical first-launch checklist:

  1. Add your production domain — https://www.example.com
  2. Add your apex domain if you also serve there — https://example.com
  3. Add staging environments — https://staging.example.com
  4. Add local dev — http://localhost:3000 (or whatever port you use). Local dev usually needs http://, not https://.

Then save and verify in each environment.

💡 Tip: It’s safe to add origins you haven’t actually launched on yet. The widget only checks at render time on each host page; an unused authorized origin has no effect.

Subdomains and wildcards

🔴 [NEEDS CLARIFICATION: Confirm whether wildcard subdomain patterns (e.g., https://*.example.com) are supported, and what exact syntax is accepted. Codebase digest doesn’t surface the matching logic.]

Until wildcard support is confirmed, the safest assumption is that each subdomain must be added explicitly:

  • ✅ https://www.example.com
  • ✅ https://blog.example.com
  • ✅ https://store.example.com

If you have many subdomains, this can be tedious; ask your account contact about wildcard support before standardizing on per-subdomain entries.

Local development

Local dev origins typically look like:

  • http://localhost:3000 (Next.js / Vite default)
  • http://localhost:8080
  • http://127.0.0.1:5173

Add the exact origin you’ll be testing against, scheme included. Browsers treat http://localhost:3000 and https://localhost:3000 as different origins.

💡 Tip: Some teams add http://localhost:* patterns expecting wildcards. As noted above, that may not work — add the specific port you use.

What visitors see when origin isn’t authorized

🔴 [NEEDS CLARIFICATION: Confirm exact widget behavior on unauthorized origin. Three plausible behaviors: (a) the widget refuses to render leaving the mount div empty, (b) the widget renders a small “not authorized” message, (c) the widget logs to the console but otherwise stays silent. Confirm with engineering.]

The most likely behavior is option (a) — the mount div stays empty and a console warning logs the failure. From the visitor’s perspective the page just doesn’t have a finder on it.

If you’re seeing a blank mount div, confirm:

  1. The origin you’re testing on is in the list
  2. The origin matches scheme + host + port exactly (http vs. https, example.com vs. www.example.com)
  3. You’ve waited ~5 minutes since adding the origin (CDN cache)

Common gotchas

Forgot to add the new domain after a re-platform

You moved from oldsite.com to newsite.com, the snippet is in place, the widget doesn’t render. The cause is almost always that the new domain isn’t on the list. Add it; wait 5 minutes; refresh.

www vs. apex

https://example.com and https://www.example.com are different origins. If your site serves on both (or redirects between them), add both — the redirect doesn’t change the eventual rendered origin, but during testing you may hit either.

http:// vs. https:// on staging

Some staging environments serve over HTTP, some over HTTPS. Match exactly what your staging URL is in the browser address bar.

Ports on local dev

Next.js defaults to :3000, Vite to :5173, and many other tools have their own defaults. Add the exact port your dev server uses.

Production domain typos

The most embarrassing failure mode. Double-check spelling on the production domain before saving. The widget won’t tell you which entry on the list is misspelled — it just doesn’t match.

When to add staging vs. when to use a separate Finder

Two patterns work:

  1. Same Finder, both origins authorized — production and staging both list as authorized URLs on the production Finder. Easier to manage; staging always reflects production data. Risk: a typo in staging’s HTML could affect what real visitors see if it propagates to production.
  2. Separate Finders for production and staging — each has its own authorized URLs (production-only and staging-only respectively). Stronger isolation. Cost: you maintain the design and refinement configuration in two places.

Most teams pick #1 unless they’re actively iterating on the design and don’t want staging-specific changes to leak.

What this is not

Authorized URLs is not:

  • ❌ A way to restrict who can see the data — the data is public-by-design (see Finder key). Authorized URLs only restricts where the widget is allowed to render.
  • ❌ A way to throttle traffic — there’s no per-origin rate limit
  • ❌ A way to A/B between origins — the same Finder renders identically on every authorized origin

For data-level restrictions, the model is to put sensitive content in a Workspace that requires authenticated access at the dashboard level, not in a public Finder.

Where to next

AnalyticsCaching