Create a UPCS Embed Session in PHP

A plain PHP script can create an embed session with the cURL extension. Wrap the call in a function, return only the token to the browser, and keep the key in the environment.

The function

<?php
function createUpcsEmbedSession(string $origin, ?int $ttl = null): array
{
    $payload = ['origin' => $origin];
    if ($ttl !== null) {
        $payload['ttl'] = $ttl; // 60-3600 seconds
    }

    $ch = curl_init('https://api.upcs.io/api/v1/embed/sessions');
    curl_setopt_array($ch, [
        CURLOPT_POST           => true,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT        => 10,
        CURLOPT_HTTPHEADER     => [
            'x-api-key: ' . getenv('UPCS_API_KEY'),
            'Content-Type: application/json',
            'Accept: application/json',
        ],
        CURLOPT_POSTFIELDS     => json_encode($payload),
    ]);

    $raw    = curl_exec($ch);
    $status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    $data = json_decode((string) $raw, true) ?: [];
    if ($status >= 400 || ($data['success'] ?? true) === false) {
        throw new RuntimeException(
            ($data['code'] ?? 'error') . ': ' . ($data['message'] ?? 'UPCS request failed'),
            $status
        );
    }
    return $data; // session_token, expires_at, embed_url
}

An endpoint for your page

<?php
header('Content-Type: application/json');
try {
    $session = createUpcsEmbedSession('https://shop.example.com');
    echo json_encode(['session_token' => $session['session_token']]);
} catch (RuntimeException $e) {
    error_log($e->getMessage());
    http_response_code(502);
    echo json_encode(['error' => 'Map is temporarily unavailable']);
}

Your page then fetches this endpoint and passes the token to UPCS.mount; the full flow is in embedding the map on a website.

Notes

• Set a timeout so a slow upstream call cannot hang your page.
• Use a fixed origin from configuration rather than a request header.
• If you receive 429, slow down; see rate limits and backoff.
• If you use Laravel, the Laravel example uses the framework's HTTP client instead.

Error meanings are listed in the error codes reference.