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
EmbeddingFinder key

Finder key

Every Finder you create has a finder key — a public token that identifies it to the embed widget. The key is the bridge between “I built a finder in the dashboard” and “the right finder loads on my visitor’s screen.” This page explains what the key is, what it grants, what it doesn’t, and how to handle it safely.

What it is

A finder key is a short, opaque string assigned to your Finder when it’s created. Every Finder has its own key; keys never overlap across Finders.

You’ll typically see it in two places:

  1. In the embed snippet — as the value of the finder-key attribute on the mount div: 
    <div id="finder-app" finder-key="YOUR_KEY"></div>
  2. In the dashboard — on the Finders list (snippet icon next to each Finder) and inside the Finder Builder’s Launch section.

🟡 [SCREENSHOT: Embed snippet modal in the dashboard with the finder key value highlighted in the displayed <div> tag.]

What it grants

The finder key is read-only and scoped to one Finder. Specifically, it grants:

  • The ability to fetch that Finder’s design and Locations from the CDN
  • The ability to post analytics events for that Finder

That’s it. Possessing a finder key gives no access to:

  • Any other Finder, even in the same Workspace
  • Your account or Workspace data
  • Edit operations of any kind
  • Other customers’ finders

What it does not grant

The finder key is not an account credential. It is not an API token. Specifically:

  • ❌ It cannot be used to call the dashboard API
  • ❌ It cannot be used to log into your account
  • ❌ It cannot be used to read another Finder’s data
  • ❌ It cannot edit your Finder’s design, locations, or settings

Treat it like a public asset — it’s meant to be visible in your HTML.

⚠️ Warning: If you have a workspace API token or JWT (these exist for programmatic access from your own backend), do not put one of those in the embed snippet by mistake. Account-level credentials grant write access; the finder key does not. Mixing them up is a serious leak.

Where to find your key

From the Finders list

  1. Open Finders in the dashboard sidebar
  2. Find the Finder you want to embed
  3. Click the snippet icon next to it
  4. The modal shows the full embed snippet with the key already filled in

🟡 [SCREENSHOT: Finders list with one row’s snippet icon highlighted, and the embed snippet modal open showing the key.]

From the Finder Builder

  1. Open the Finder
  2. Open the Launch section
  3. The embed snippet (with the key filled in) is shown there alongside the Authorized URLs panel

Where to put the key in the snippet

Put it on the mount div as a finder-key attribute:

<div id="finder-app" finder-key="YOUR_KEY"></div>
<script type="module" src="https://cdn.locationfinders.com/snippet.js"></script>

This is the recommended placement. The script reads the attribute from the div with id="finder-app" and uses it to fetch the right Finder.

A legacy alternative — the key as a query parameter on the script URL — also works for backward compatibility but is not recommended for new embeds:

<!-- Works but not recommended -->
<script type="module" src="https://cdn.locationfinders.com/snippet.js?key=YOUR_KEY"></script>

The attribute form keeps the key adjacent to where the widget will render, which is easier to read and easier to update without touching the script tag.

Sharing keys across teams or environments

Because the key is public-by-design, you can:

  • Paste it into staging and production — the same key can be used in both, as long as both origins are on your Finder’s Authorized URLs list
  • Share with your developer — emailing a finder key is fine; it’s not a secret
  • Commit it to source control — finder keys belong in the host page’s HTML, which is typically committed

What you can’t do:

  • Use one Finder’s key in two different Finders’ embed snippets — every key maps to exactly one Finder; if you want different finders on different pages, you need different Finders (each with its own key)

Rotating a key

🔴 [NEEDS CLARIFICATION: Is there an in-app “rotate finder key” action? Not visible in the codebase digest. If not, document the workaround (delete + recreate the Finder, then update every embed snippet).]

If you need to invalidate a key — for example, you suspect someone copied your snippet onto an unauthorized site (though Authorized URLs is the actual protection against that) — the workaround today is:

  1. Duplicate the Finder
  2. Verify the duplicate has all the locations and design you expected
  3. Update the embed snippet on every host page to use the duplicate’s key
  4. Delete the original Finder

The new Finder gets a new key; the old key stops working when the Finder is deleted.

What changes if a Finder is deleted

If you delete a Finder, its key stops working immediately. Any host page still using the old key will show a blank widget (or a “finder not found” state — see Troubleshooting the embed).

This is intentional: deleting a Finder should propagate quickly. Plan deletes accordingly.

Why DropAFinder doesn’t make keys “secret”

A common security instinct is to hide identifiers and require authenticated requests. For visitor-facing embeds that approach doesn’t work — there’s no place to keep a secret in a <script> tag on a public web page. So DropAFinder uses a different shape:

  1. The key is public and visible in HTML
  2. The key grants read-only access to one Finder’s design + locations + analytics ingestion
  3. Origin enforcement (via Authorized URLs) prevents the snippet from rendering on domains you didn’t approve

The result: keys can leak without exposing your account, and the only damage someone copying your snippet can do is render your finder on their site — which Authorized URLs blocks anyway.

Where to next

CachingPreview mode