Embed Session TTL and Renewal

An embed session is a short-lived credential for one origin. You decide how short by sending ttl in seconds when you create it; the allowed range is 60 to 3600 and the default is 15 minutes (900 seconds).

Reading the response

{
  "session_token": "...",
  "expires_at": "...",
  "embed_url": "..."
}

expires_at tells you when the session stops working. Use it, rather than a hard-coded number, to decide when to renew.

Choosing a value

Situation	Suggestion
Quick checkout map	The default 15 minutes is usually plenty
Long forms or support tools left open	Longer, up to 3600 seconds, or renew on demand
Public pages with high traffic	Short, and create sessions only when the map is opened

A shorter TTL limits the usefulness of a copied token. A longer one means fewer renewals and fewer API calls against your hourly limit. Balance the two.

Request a session lazily

Do not create sessions for visitors who never open the map. Create the session when the map section becomes visible, or when the visitor clicks "Choose on map". That saves requests; see rate limits and backoff.

Renewal approaches

1. On error. Wait for session_expired and recover, as in handle onError and session_expired.
2. Before expiry. Use expires_at to schedule a fresh session slightly early, then destroy and remount; see embed lifecycle.
3. On user action. Ask for a new session when the user returns to a tab that has been idle.

The first approach is the simplest and is a sound default. Keep the visitor's chosen code outside the map so renewal does not cost them their work.

Server-side reuse

You may reuse a valid session across requests for the same origin, but do not share tokens across origins or users unnecessarily. Details of the call are in creating a session with cURL.