Web Tracking Keys
Mint Web Tracking Identity
Mint a short-lived proof that lets the browser or mobile SDK attach events to one authenticated contact
POST
Mint Web Tracking Identity
Call this endpoint from your authenticated backend after you know who the
current user is. It returns a short-lived token bound to the workspace, web
tracking key, the user’s normalized email, your own user ID (
Pass the returned token to the browser and identify the same email:
For an app user known by your own ID, mint for the
externalId), or
both, and an expiry.
Never call this endpoint from browser code or expose the secret API key used to
authorize it. A publishable tracking key alone may append anonymous activity,
but cannot attach events to a subscriber or trigger automation.
If the user is not yet a contact in your workspace, minting creates one so the
identified events have somewhere to land - otherwise they would be accepted and
then silently dropped. An externalId alone creates a contact with no email,
for users who signed in without one (Sign in with Apple with a hidden address,
phone login). Minting with both links them: the external ID is attached to the
email’s contact, and a contact that had only that external ID is merged into
it (its devices, tokens and missing attributes move; its own events, tags and
lists do not). If the email and the external ID already belong to two
different contacts, or the email’s contact already has a different external
ID, the request fails with a 409. The contact is created active with no list memberships
and without triggering any automations; enroll it through your usual flows when
you want more than event attribution. If the email cannot be added as a contact
(for example a suppressed or undeliverable address), the request fails with a
400 and no token is minted.
Requires commerce:write, automations:trigger, and subscribers:write (minting can create the contact).
Request
Identify the key by eitherkeyId or publicKey. The publishable key is the
value in your snippet and in the dashboard, so it is usually the one your
backend already has.
Email of the user authenticated by your backend. It is normalized to
lowercase. Provide
email, externalId, or both.Your own ID for the user, up to 255 characters. Case-sensitive; surrounding
whitespace is trimmed. Use it for users without an email, or pass it with
the email so the contact keeps your ID. The SDK must then identify with the
same identifiers (
identifyUser in the mobile SDKs).Token lifetime from 1 minute through 30 days. Defaults to 24 hours. Mint a
fresh token when the user signs in or reaches checkout; request a longer
lifetime only when re-minting is genuinely impossible.
externalId (and the
email, when you have one) and identify with exactly those values: