Docs

Guide: anonymous → identified

Capture consent before someone logs in, then attach it to their account so nothing is lost.

The problem: a visitor sets their cookie preferences before they have an account. Later they sign up. You don’t want to ask again, and you don’t want their earlier choices stranded on an anonymous record.

The fix: record the anonymous visitor against a cookie_id, then merge that into their real identifier at login. The merge moves every vault row and identifier across; future reads by email: include everything they decided while anonymous.

const visitor = 'cookie_id:' + getOrCreateVisitorCookie();

await tc.recordConsent({
  subject: visitor,
  purpose: 'analytics',
  state: 'GRANTED',
  channel: 'cookie_banner',
});

Merge needs a secret key (sk_…) — do it server-side, once, as part of your login flow.

await tc.mergeSubjects(
  'cookie_id:' + visitorCookieFromRequest,
  'email:' + user.email,
  'login',   // free-text reason, stored on the merge
);

From here, GET /v1/subjects/email:…/consent reflects the anonymous history too. A subject.merged webhook fires if you need to sync anything in your own systems (not when the response says device_relinked). Merging the same pair again is a no-op.

If both sides already had a decision for the same purpose, the most recent one wins — the older row stays in the history, superseded.

Shared devices: if the cookie_id / device id already belongs to a different signed-in account (a second person logging in on the same browser), the two accounts are not merged. Only the device is re-linked to the account signing in, and the response says outcome: "device_relinked" with movedRecords: 0. Each account keeps its own consent and preferences.

After the merge, the browser needs an identity token to read or write that person with a pk_ key — see Guide: identifying logged-in users.

Guide: anonymous → identified

Before login (browser)

Right after login (your server)