Skip to main content
Version: Current platform

API Authentication

Upsurge separates site-scoped public traffic from signed-in merchant operations.

Secret REST API key​

Server-to-server integrations send a scoped secret key in X-API-Key:

X-API-Key: upsurge_sk_live_replace_me

Secret keys are created in Dashboard → API Keys for one site, shown once, and must have explicit permissions. New merchant keys cannot use wildcard permission. See Sites and API keys.

Available scopes include:

  • events:track
  • events:read
  • recommendations:read
  • search:read
  • catalog:write
  • overlays:read
  • overlays:submit
  • chatbot:access
  • workflow_commands:access
  • conversions:track
  • conversions:read
  • partner_attribution:touch
  • partner_attribution:convert
  • partner_experiments:assign
  • attribution:touch
  • commerce:convert
  • profiles:write
  • product_embeddings:read / product_embeddings:write

Experiment management is available only through Firebase-authenticated merchant dashboard routes under /experiments; API keys do not grant that authority.

Browser runtime token​

The browser receives only the public siteId. The SDK posts it to /api/v1/sdk/bootstrap from the registered storefront origin and receives a 15-minute AES-256-GCM runtime token. Browser API requests use:

Authorization: Bearer RUNTIME_TOKEN

Runtime tokens are tenant/site/origin bound and carry only browser-safe capabilities. Every token includes event ingestion, workflow commands, attribution touches, and partner-experiment assignment. Search, recommendations, overlays, and chatbot capabilities are added only when those features are enabled for the site.

Bootstrap can fail with origin_required or site_not_available (403), rate_limit_exceeded (429), or runtime_limiter_unavailable (503). Unload beacons may place the token in the JSON body only on explicitly supported ingestion routes. Tokens never belong in URLs or persistent storage.

Key environments​

  • upsurge_sk_test_… is generated outside production.
  • upsurge_sk_live_… is generated in production.

The prefix communicates the deployment, but the API still validates the full key record and status. Do not infer access from the prefix alone.

Credential handling​

  • Store server-side copies in a secret manager or encrypted environment configuration.
  • Never place a secret key in browser code, public configuration, a request URL, or a beacon body.
  • Treat site IDs and runtime tokens as observable; rely on origin binding, capabilities, App Check, quotas, and server authorization.
  • Never log full keys, bearer tokens, worker secrets, or webhook secrets.
  • Use the displayed key prefix and response request_id when troubleshooting.
  • Rotate a key immediately if it appears outside the intended integration.