API authentication

ConverStream uses two keys with different trust levels. Choosing the right one for each call keeps your data accurate and your account secure.

Public site key

  • Safe to embed in browser JavaScript and your tracking snippet.
  • Sent in the request body as site_key (or the X-Site-Key header).
  • Can only record clicks and conversions for your account — it cannot read, edit, or export data.

Secret API key

  • Server-side only. Never expose it in client-side code or public repositories.
  • Sent in the Authorization header as a bearer token: Authorization: Bearer SECRET_API_KEY.

When to use which

ScenarioKeyHow it's sent
Tracking snippet in the browserPublic site keysite_key in body
POST /api/v1/clicksPublic site keysite_key in body
Browser conversion (trackConversion)Public site keysite_key in body
Server-side conversionSecret API keyAuthorization: Bearer

Unauthorized responses

Any request with a missing or invalid key is rejected with 401 Unauthorized and a JSON body:

{ "error": "unauthorized" }