UPCS Map Session Expiry and Renewal

A map session token is short-lived by design. If a page sits open longer than the session, the map stops accepting requests until you provide a new token.

How long a session lasts

• The default is 15 minutes.
• You can set ttl between 60 and 3600 seconds when you create the session.
• The response includes expires_at, the time after which the session no longer works.

What an expired session looks like

Requests return HTTP 401 with the code session_expired. In the page, the onError callback you passed to UPCS.mount is called.

Other things can end a session early: removing the allowed origin or disabling the key stops dependent sessions at once. See error codes explained.

Choose a sensible ttl

• For a checkout where users finish in minutes, the default is usually enough.
• For longer forms, raise ttl, but not further than you need.
• Shorter sessions reduce the damage if a token leaks.

Renew a session

1. Keep expires_at from the session response.
2. When onError reports session_expired, or shortly before expires_at, ask your server for a new session.
3. Call destroy() on the existing map.
4. Mount again with the new sessionToken.

function renew() {
  fetch('/your-server/upcs-session', { method: 'POST' })
    .then(function (r) { return r.json(); })
    .then(function (data) {
      map.destroy();
      map = UPCS.mount('#upcs-map', { sessionToken: data.session_token });
    });
}

Your own endpoint should create the session with the API key; never put the key in the page. See the security checklist.