Skip to content
Log in

Tracking

Send events from your backend

Create a tracking API key, send it as X-Api-Key, and rotate or revoke it when it has been exposed.

A tracking API key lets your own backend send events to Tracking. It is a secret that identifies one product, and it belongs on your server — never in a browser, a mobile app, a public repository or anywhere a visitor could read it.

The tracking script does not use a key and never needs one. Keys exist for the things the browser cannot see: a payment confirmed by your payment provider, a subscription renewal, a refund, an order that completes on a checkout you do not host.

You manage keys on the API keys page. Tracking ships no key tool of its own, so this is work you do by hand rather than from an agent.

Create a key

  1. Press Create key and give it a name you will recognise later — Production backend, Billing worker. The name is for you; it has no effect on what the key can do.
  2. Copy the secret from the dialog that opens. It is shown once, at that moment, and stored wherever your backend keeps its secrets.
  3. Copy the endpoint from the same page. It shows the finished address for your product, with a button to copy it.

Only a hash of the secret is kept, so nobody — including Lessly — can show it to you again. Lose it and your only option is to rotate the key. A secret starts with sk_live_ followed by 48 hexadecimal characters.

Use it

Send your events to the events endpoint with the key in the X-Api-Key header — not Authorization:

X-Api-Key: sk_live_YOUR_KEY_HERE

What the request body looks like, which six event names are accepted and how revenue is expressed are on Send revenue from your backend. The route, its status codes and its schema are on the Tracking API reference.

A key is bound to the product it was created in. A request is refused if the key does not belong to the product it is being sent to, so a key from your staging product cannot write into your production one by mistake. A missing or unrecognised key is refused as well.

Two consequences worth planning for:

  • Each product needs its own keys. There is no key that spans products.
  • A key that belongs to a product can send any event that product accepts. There is no narrower permission than that — which is why a key per system is worth the small extra effort.

Read the list

Every key in the product is listed with:

ColumnWhat it tells you
NameWhat you called it.
KeyThe first characters and the last four of the secret — enough to tell two keys apart in a log. Never the whole thing.
Statusactive or revoked.
Created, Last usedRelative times. Last used is stamped after a request authenticates successfully, so it is the honest answer to “is anything still using this key?”

A key that reads Never long after you deployed it means your backend is not reaching Tracking with it. Last used is written as a side effect of a successful request and is never allowed to hold one up, so treat it as accurate to within a moment rather than to the second.

Rotate a key

Rotate replaces a key: a new secret is issued and the old one is revoked in the same step, and the replacement keeps the old key’s name. The new secret is shown once, in the same dialog as at creation.

There is no overlap period. The old key stops working immediately, so a backend still holding it starts getting refused right away. Have the new secret ready to deploy before you rotate, and rotate at a moment you can follow through.

Rotate when a secret may have been exposed — a leaked log, a laptop that left the building, someone who has moved on — and on whatever schedule your own policy sets. Only active keys can be rotated.

Revoke a key

Revoke disables a key permanently and cannot be undone. Anything using it is refused from that moment.

A revoked key is not deleted. It stays in the list with the status revoked, so the record of what existed and when it was last used survives. Only active keys offer Rotate and Revoke.

Revoke a key you have retired rather than leaving it active and unused: an active key nobody is watching is the one that gets found.

Keep keys safe

  • One key per system that sends events. When something goes wrong you can rotate exactly that one, and Last used tells you which key is which.
  • Keep secrets in your deployment’s secret store, not in source control or a configuration file that travels with your code.
  • Never put a key in anything that runs in a browser. The tracking script covers what happens in the browser and needs no key.
  • Rotate on a schedule you decide in advance, and revoke keys you no longer use.

Next steps

Was this page helpful?
Esc

Start typing to search the docs.

↑↓navigate↵select