UPCS Logo
    My Account

    API and developers

    Create a UPCS Map Session From Your Server

    Create a short-lived UPCS map session with POST /v1/embed/sessions, pass your origin and optional ttl, and read the session token from the response.

    Updated 14 October 2026 · 2 min read

    A map session is a short-lived token that lets one page load the embedded map without your API key being exposed. Your server creates it, and the browser uses it.

    The request

    POST https://api.upcs.io/api/v1/embed/sessions

    Headers:

    • x-api-key: your API key.
    • Content-Type: application/json.

    Body:

    {
  "origin": "https://shop.example.com",
  "ttl": 900
}
    Field Required Notes
    origin Yes The https origin where the map will run. Must be an allowed origin.
    ttl No Lifetime in seconds, 60 to 3600. Default is 15 minutes.

    The response

    The response includes:

    • session_token: give this to the page.
    • expires_at: when the session stops working.
    • embed_url: the URL used by the embedded map.

    Steps

    1. Call the endpoint from your server, never from browser code.
    2. Read session_token from the response.
    3. Hand it to the page, for example in a template variable or a small authenticated endpoint.
    4. In the page, pass it to UPCS.mount.

    Common failures

    • 403 origin_not_allowed: the origin is not registered in your partner panel, or was removed.
    • 401 "Invalid or inactive API key" (no code): the key is wrong, disabled, expired or deleted. A missing key returns 401 "Missing API key".
    • 403 partner_required: the key does not belong to a partner account.
    • 422: the origin is invalid or not an expected value.
    • 429 rate_limited: the key has reached its hourly limit.

    All are described in error codes explained. For how long sessions live and how to renew them, see session expiry.

    Frequently asked questions

    How long does a session last?

    15 minutes by default. You can set ttl between 60 and 3600 seconds.

    Related reading

    Mount the UPCS Map With UPCS.mountUPCS.mount renders the map in a page element. See the options for session token, height, center, zoom and style, the callbacks and how to destroy it.Read the UPCS Map Click ResponseThe onSelect callback receives the UPCS code, latitude, longitude, address, country code, cell bounds, saved status and share URL. See each field.Resolve Coordinates to a Code Server-to-ServerUse POST /v1/embed/resolve with latitude and longitude to get a UPCS code from your server without showing the map, and optionally save the result.UPCS Quick Start: Your First Five MinutesGenerate, share and look up a UPCS code in a few steps. A short walkthrough for first-time users of upcs.io.