Skip to content
Contact us
Documentation menuSources and keys

Sources and keys. Who sends, with what.

Every client that sends data to an app is a source and proves who it is with its own keys. Keys belong to a source and an environment; revoking one never affects other sources.

Source kinds and environments

The source kind is chosen at creation and cannot change. The environment decides which traffic the screens show; production is the default.

KindFor
webA website or web app; the script tag or the npm package.
ios, androidA mobile app (the mobile SDK comes in a later stage; HTTP works today).
serverThe product’s server; signed requests are recommended.
otherAnother client, e.g. a Segment-compatible library.

Write key (pk_…)

Starts with pk_live_ or pk_test_ and has 32 more characters. It may sit in the open in browsers and mobile apps: it can only send data, never read. Only its hash is stored.

A request carries it as the HTTP Basic user name (empty password, Segment-compatible), with Authorization: Bearer, or in the writeKey field of the body of a browser beacon.

Signing secret (sk_…)

Starts with sk_live_ or sk_test_ and has 48 more characters. Used on servers only, it signs the request with the Metrics-Signature header. With Signature required on the source, an unsigned request gets 401 signature_required.

Test keys

Every event sent with a _test_ key is marked as test; screens leave test traffic out by default. To count a single event sent with a live key as test, set properties.test: true.

Allowed origins and excluded paths

  • For web sources, a request whose browser Origin is not among the allowed origins gets 403 origin_not_allowed.
  • Excluded paths (patterns such as /panel, /account/*, /**/private) turn automatic capture off; events sent from those pages carry the page as [excluded].
  • Both change in the panel and reach the SDK through remote configuration (GET /v1/config/{writeKey}); no code change is needed.

Key rotation

  • Create a new key and roll it out.
  • Revoke the old one with a grace period: at once, 1 hour, 24 hours or at most 7 days. During it the key keeps working in the “expiring” state, then it is refused.
  • While a signing secret is rotated, a request may carry several v1= signatures; one valid signature is enough.

Related pages