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
CustomizationAuthorized URLs

Authorized URLs

Every Finder has an Authorized domains list — an allowlist of origins that are permitted to embed the widget. This page covers how to manage that list in the Finder Builder. For the embedding-side perspective (what to add, when to add it, and common gotchas), see Authorized URLs (embedding).

Where to find it

The setting lives in the Launch group of the Finder Builder sidebar, under Authorized domains.

  1. Open your Finder in the Builder.
  2. In the sidebar, click Authorized domains (under the Launch group).
  3. The panel shows every origin you’ve already added and an input field to add more.

🟡 [SCREENSHOT: Authorized domains panel in the Finder Builder showing the list of existing origins, the text input, and the Add button. Sidebar “Authorized domains” item is selected and shows a warning glyph when the list is empty.]

The sidebar shows a warning indicator next to Authorized domains when the list is empty, and a checkmark once at least one origin is saved. The panel also displays the message “Add at least one before publishing” when the list is empty.

Adding an origin

  1. Type the origin into the input field. The placeholder reads e.g. yoursite.com.
  2. Press Enter or click Add.
  3. The origin appears in the list above the input.
  4. Click Save (or publish) to persist the change.

You can add as many origins as you need. There is no documented upper limit.

Removing an origin

Each listed origin has a Remove button to its right. Clicking it removes the entry immediately from the in-memory state. The change is not committed until you save.

How origins are matched

The check happens server-side when the widget fetches its configuration. The server reads the Origin (or Referer) header from the request and compares the host portion against the host portion of each entry in your list.

Key matching rules:

  • Host-only comparison. The scheme and port in the entry you type are stripped away; only the hostname is compared. https://www.example.com and http://www.example.com resolve to the same stored host (www.example.com) and will both match a request from either scheme.
  • Exact host match. www.example.com and example.com are treated as different hosts. Add both if your site serves on both.
  • localhost and 127.0.0.1 are always allowed. You do not need to add a localhost entry for local development — the server grants these automatically.
  • No wildcard support confirmed. Each subdomain must be added as a separate entry. If you need www.example.com, blog.example.com, and store.example.com, add each one.

🔴 [NEEDS CLARIFICATION: Confirm whether wildcard subdomain patterns are supported in the URL input (e.g., *.example.com). The matching logic in ExternalController.php compares hosts exactly, so wildcards in the stored entries would not match. Verify with engineering before documenting wildcard support.]

What happens when an origin is not on the list

If the list is non-empty and the requesting origin is not on it, the server returns a 403. The widget then renders the Finder unavailable error state — a grayed-out skeleton with an error card overlay — instead of the live finder. The page itself is not affected; only the widget’s mount point shows the error. There is no redirect or browser-level block.

If the list is empty, all origins are allowed. This is the default state for a newly created Finder. The sidebar shows a warning indicator on the Authorized domains item to remind you to add at least one origin before publishing.

💡 Tip: If your widget is showing “Finder unavailable” on a site you control, the first thing to check is whether that site’s hostname is in your Authorized domains list.

Local development

localhost and 127.0.0.1 are always allowed by the server, regardless of whether you’ve added them to the list. You can safely test locally without adding a localhost entry.

If you use a non-standard local hostname (for example, a .local domain from a tool like Laravel Herd or a custom /etc/hosts entry), add that hostname explicitly since it will not match the localhost shortcut.

Relationship to the Finder key

Authorized domains and the Finder key work together but protect different things:

  • The Finder key identifies which finder to load. Anyone who can read your page source can see it.
  • Authorized domains restricts which hostnames the server will respond to. Even if someone copies your Finder key, the server will refuse requests from domains not on your list.

Neither mechanism encrypts the location data itself — the data is public by design. See Finder key for more on the key’s role.

Where to next

Advanced refinementsCustom colors