Get started
Map Publishing

Session tokens

Session tokens

When your organization turns on Require session token, the embed needs a short-lived token beside its publishable key. Your server mints it, a script on your page hands it to the embed, and the embed asks for a new one before it expires.

1

Add an endpoint that mints a token

Serve GET /api/mountaya-embed-session from your backend. It calls POST /v1/sessions with your secret key and the embed's publishable key, and returns the session.

curl -s -X POST https://api.mountaya.com/v1/sessions \
  -H "X-API-Key: $MOUNTAYA_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"publishable_key\": \"$MOUNTAYA_PUBLISHABLE_KEY\"}"
Response
{
  "data": {
    "expires_at": "2026-11-09T11:13:20.995806Z",
    "token": "sess_your_session_token",
    "user_id": null
  }
}

Send no user_id. The token then reads only what you publish, like the key alone.

2

Answer the embed from your page

Paste this script once per page, beside the iframe. It answers every embed on the page from your endpoint.

<script>
  // Answers each Mountaya embed's request for a session token from your endpoint, which
  // calls POST /v1/sessions with your secret key and answers its body, or the session in it.
  (function () {
    var origin = "https://app.mountaya.com";
    var endpoint = "/api/mountaya-embed-session";
    if (window.mountayaEmbedSession) return;
    window.mountayaEmbedSession = true;
    window.addEventListener("message", function (event) {
      if (event.origin !== origin || !event.data) return;
      if (event.data.type !== "mountaya:requestSessionToken") return;
      var frame = event.source;
      fetch(endpoint, { credentials: "same-origin" })
        .then(function (response) {
          if (!response.ok) throw new Error("Session endpoint answered " + response.status);
          return response.json();
        })
        .then(function (body) {
          var session = body && body.data ? body.data : body;
          if (!session || typeof session.token !== "string") {
            throw new Error("Session endpoint answered no token");
          }
          if (typeof session.user_id === "string") {
            throw new Error("Session endpoint answered a token naming a user: mint without user_id");
          }
          frame.postMessage(
            { type: "mountaya:setSessionToken", token: session.token, expiresAt: session.expires_at },
            origin
          );
        })
        .catch(function (error) {
          console.error(error);
        });
    });
  })();
</script>

When your organization requires session tokens, the embed snippet you copy from Map Studio already carries this script. Change endpoint if yours lives elsewhere.

3

Keep the iframe as it is

The iframe from the quickstart needs no change. The embed asks your page for its first token as it loads.

How renewal works

WhenThe embedYour page
It loadsPosts mountaya:requestSessionTokenFetches a token and posts mountaya:setSessionToken
A minute before expires_atAsks againAnswers again
An ask goes unansweredKeeps its token and asks again a minute laterLogs the failure on the console

The embed sends the new token with its next request, without reloading.

Optional: a first token in the src

You may also append &session_token=sess_your_session_token to the iframe src. The embed uses it only until the script first answers, so keep the script.

Troubleshoot

  • The map stays blank, then gives up. The embed waited 10 seconds for a token. Check that the script is on the page and that your endpoint answers 200.
  • The console says the token names a user. Mint without user_id.
  • The map loads, then stops after a few minutes. Your endpoint failed on a renewal. The console names the status it answered.

Next steps

Last updated