Protect an embedded map

Configure access in Maphere

1. As a workspace owner/admin, open Share and save the Protected access mode before the first publication of a sensitive map.
2. Publish the reviewed map, enable website embeds, and save your exact website origin. A plain iframe cannot authorize a protected map.
3. Open Developer access & API keys. Create a named key with only Create viewing tokens (viewer:tokens), and choose its expiry. A viewer-only integration needs no content-field grants.
4. Store the one-time secret in your backend’s secret manager. Copy the SDK map ID separately. Never send the mhk_ secret to a browser, URL, analytics tool or public environment variable.

How protected viewing works

The diagram combines the browser SDK and hosted iframe as the visitor side. Their messages validate the parent window, exact origins and connection challenge. Tokens remain in memory; do not put them in iframe URLs, browser storage or cookies.

Add your backend token endpoint

import { createMapApi } from "maphere-sdk/server";
// Implement these checks in YOUR application. They are not SDK functions.
import { authorizeMapVisitor } from "./your-auth";

const api = createMapApi({ apiKey: process.env.MAPHERE_API_KEY! });
const mapId = "33333333-3333-4333-8333-333333333333";
const parentOrigin = "https://portal.example.com";
const headers = { "Cache-Control": "private, no-store" };

// Mount at POST /api/map-token on YOUR backend.
export async function POST(request: Request) {
  // Must check sign-in, permission for this venue, CSRF and rate limits.
  if (!(await authorizeMapVisitor(request, mapId))) {
    return Response.json({ error: "Not authorized" }, { status: 403, headers });
  }
  try {
    const session = await api.createViewerSession(mapId, parentOrigin, {
      signal: request.signal,
    });
    return Response.json(session, { headers });
  } catch {
    return Response.json({ error: "Map access unavailable" }, { status: 503, headers });
  }
}

The server client can be used from any supported Node.js backend. The POST export illustrates a Next.js route handler; adapt the Request/Response boundary for your framework. Use HTTPS and preserve no-store headers on successes and failures.

Connect the browser callback

Use the map container and status element from Embed with the SDK. The callback runs for the first connection and again on renewal. Pass its AbortSignal through to fetch, and include your application’s required CSRF header.

import { createMap } from "maphere-sdk";

const map = createMap("#map", {
  mapId: "33333333-3333-4333-8333-333333333333",
  getViewerToken: async ({ signal }) => {
    const response = await fetch("/api/map-token", {
      method: "POST",
      credentials: "same-origin",
      cache: "no-store",
      signal,
      // Add the CSRF header required by your application's backend.
    });
    if (!response.ok) throw new Error("Map access unavailable");
    return response.json(); // Short-lived { token, expiresAt }.
  },
});
map.on("error", () => {
  document.querySelector("#map-status")!.textContent =
    "Map access ended. Sign in and reconnect.";
});
void map.ready.catch(() => map.destroy());
window.addEventListener("pagehide", () => map.destroy(), { once: true });

Renewal, revocation and testing

• Test an authorized visitor, an unauthorized signed-in visitor and a signed-out visitor.
• Open the direct viewer, old image URL and a protected resource without a token; none should expose the protected map.
• Test key revocation, expiry, backend denial and offline behavior. Confirm the loaded viewer clears and the host shows a recovery action.
• For routine key rotation, create a replacement, update the backend, verify a fresh connection, then revoke the old key. Existing sessions from the old key will end.