Quickstart

Embedding the studio is a single <iframe> pointed at https://app.mountaya.com/studio/embed with your credentials and configuration in the query string. This guide gets a live, interactive map onto your page in three steps, in about two minutes: get a publishable key, optionally mint a session token, then paste the embed markup.

Get a publishable key

Map Embedding authenticates with a publishable key (pk_…) that carries the embedding scope. Create one from your Mountaya dashboard under Settings → API keys and enable the embedding scope (which requires the tiles scope, since the studio renders tiles).

The publishable key is safe to ship in a browser, but it is restricted to the origins you allow. Add the domain that will host the iframe to the key's allowed origins, or the embedded document is refused. See authentication for the full key and scope model.

Mint a session token, if your organization requires one

A publishable key with origin validation is enough for most embeds. If your organization enables session enforcement (require_session_token), you must also pass a short-lived session_token. Mint one server-side by calling POST /v1/sessions with your secret key, then hand the returned sess_… token to the page that builds the iframe.

curl -X POST https://internal.mountaya.com/v1/sessions \
  -H "X-API-Key: sk_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{"publishable_key": "pk_your_publishable_key"}'

Tokens live for 5 minutes, so mint a fresh one each time you render the iframe. The full flow, including reading the token and its expiry, lives on the authentication page.

Never put a secret key in the iframe

The iframe src is fully visible to the browser. Only the publishable key and the session token may appear there. The secret key is server-side only and must never reach a URL.

Add the iframe to your page

Point an <iframe> at the embed route with your publishable key and any configuration as query parameters. The example below pins the topographic basemap and turns on the overlays and preferences controls.

<iframe
  src="https://app.mountaya.com/studio/embed?publishable_key=pk_your_publishable_key&terrain=topo&with_overlays_control=true&with_preferences_control=true"
  title="Mountaya map"
  width="100%"
  height="520"
  style="border: 0; border-radius: 8px;"
  loading="lazy"
></iframe>

That is a complete, interactive embed. To show specific content, add an itinerary_id, collection_id, or zone_id. To change the look and which controls appear, add the display and with_* parameters. The full set is on the parameters page.

Troubleshooting

A few issues come up often when wiring up a first embed:

The embed is blank or refused. The publishable key restricts which sites may frame the map. Add the exact domain that hosts the iframe to the key's allowed origins.
The map loads but a private itinerary shows nothing. A private itinerary renders only in your own authenticated preview, never to an anonymous visitor through the snippet. Make the itinerary public to share it through an embed.
A working embed stops loading after a few minutes. Session tokens expire after five minutes. Mint a fresh session_token each time you render the iframe rather than reusing one.
The map never appears and no content loads. The publishable key must carry both the embedding and tiles scopes and must not be revoked.
A control or panel you enabled does not show up. Your organization's safety rules can lock capabilities off for embedded visitors. The embed enforces them server-side, so a restricted control stays hidden regardless of the iframe parameters.

Next steps

Iframe parameters

Every query parameter the embed accepts: content selection, display, viewer preferences, and UI controls.

Iframe events

Drive the embed at runtime with postMessage: switch the displayed content and react to the ready event.