Create a UPCS Embed Session with cURL

cURL is the quickest way to confirm that your key and origin work before you write any application code. One request creates an embed session and returns the token your page will use to mount the map.

The request

Set your key in an environment variable so it does not end up in shell history files or scripts:

export UPCS_API_KEY="upcs_your_key_here"

curl -sS -X POST https://api.upcs.io/api/v1/embed/sessions \
  -H "x-api-key: $UPCS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"origin":"https://shop.example.com"}'

To choose a lifetime, add ttl in seconds (60 to 3600):

curl -sS -X POST https://api.upcs.io/api/v1/embed/sessions \
  -H "x-api-key: $UPCS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"origin":"https://shop.example.com","ttl":600}'

The response

A successful call returns JSON with three fields you care about:

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

Pass session_token to UPCS.mount as sessionToken. Use expires_at to decide when to request a new session; see embed session TTL and renewal.

If something goes wrong

Failures return JSON with success: false, a message and sometimes a code:

• 401 when the x-api-key header is missing, or the key is invalid or disabled.
• 403 with partner_required or origin_not_allowed.
• 403 when the request comes from an IP address that is not allowed for the key.
• 422 when the origin is missing or not a valid origin, or ttl is outside 60 to 3600.

The full list is in the error codes reference.

Next steps

Once the call succeeds, move it into your backend. Examples exist for Node.js, PHP and Python. Never run this call from browser code, because that would expose your key; see how to secure your API key.