Zum Hauptinhalt springen
Version: Aktuelle Plattform

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 separately from sites, shown once, and must have explicit permissions. New merchant keys cannot use wildcard permission. Wildcard access remains supported only for previously issued secret administrator credentials.

Available scopes include:

  • events:track
  • events:read
  • recommendations:read
  • overlays:read
  • overlays:submit
  • chatbot: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. Unload beacons may place the token in the JSON body only on explicitly supported ingestion routes. Tokens never belong in URLs or persistent storage.

Publishable keys are retired

Legacy publishable and missing-class keys are rejected with publishable_key_retired. Migrate browser installs to siteId; never replace the old browser key with a secret key.

Merchant ID token​

Dashboard management endpoints require a Firebase ID token:

Authorization: Bearer FIREBASE_ID_TOKEN

The server verifies the token and applies merchant membership, role, and subject/action authorization. A secret API key is not a substitute for dashboard authorization, and neither credential should ever be embedded in storefront code.

ID tokens expire and must be refreshed through the signed-in Firebase client session. Obtain them from the authenticated application, not from the API Keys page.

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.