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.