identify — who they are
email, name, company and phone are encrypted at rest. The email is
additionally indexed by a keyed hash, so contact lookup and email search keep
working without decrypting anything.
plan is the user’s plan in your product, as a display name. It is stored
plaintext because it is not personal data — and it has no effect on your Peeve
entitlements, which come from your own subscription.
createdAt is worth setting. It is how Peeve distinguishes a genuine new signup
from an existing customer browsing logged out, so a returning user is not
miscounted as a visitor-to-user conversion.
Identity is never trusted for authentication. Anything the browser sends
in
contact is enrichment only — it cannot resolve a workspace, grant access,
or read another person’s data. The workspace always comes from the validated
key. A signed id is the one narrow exception: see
Signed identity.Signed identity
Everythingidentify sends is a claim. It runs in your page, and the
publishable key beside it is public, so anyone could post any id and any
email. That is fine for what identify was built for — the signed-in interlocks,
lead qualification, continuity across sessions — because those only shape what
the widget does inside that person’s own browser.
It is not enough to act on an account. For that, your backend signs the id.
Sign through
window.peeve.identify. The script tag’s data-user-* identity
has no attribute for a signature, so a tag-only install is always an unsigned
claim. @peeve/sdk forwards a userHash you pass to Peeve.identify, but
its IdentifyTraits type does not declare the field yet, so TypeScript will
flag it.The email is a separate claim
Signing the id proves who the person is. It says nothing about theemail
sitting next to it, which the same page can still rewrite — and an address
swapped in for someone else’s would otherwise drive a billing lookup. So the
email carries authority only when you sign it too, by signing
userId + "\n" + email in place of the id alone. Unsigned, the identity is
still verified and the email simply counts for nothing.
Verification fails closed in every direction: no id, no signature, a
malformed or wrong signature, or no secret configured all mean not verified.
The cost of a false negative is one unpersonalised turn; the cost of a false
positive is one customer’s data reaching another.
setContext — what you know about them
The server-side equivalent
Both have a server-side counterpart onPOST /v1/users, so you can establish a complete
contact before the person ever opens a browser:
identify; the attributes object is
setContext. A later browser identify with the same external_user_id merges
into the same record.
Identity is keyed on your id, not on the key
A contact is identified by(workspace, external_user_id). It is deliberately
not keyed on the API key — if it were, every user would be orphaned the day you
rotated a key, and their history would vanish.
So: use a stable id. Your internal user id is right. An email address is
usable but changes; a session id is not an identity at all.
Anonymous visitors
Before someone signs in, Peeve still tracks them, using a persistent browser visitor id. When you later callidentify, the pre-login history links to the
now-known user.
This is why calling identify at the right moment matters: it is what joins
“someone browsed pricing three times” to “Dana signed up”.
On logout
Vendor tokens
POST /v1/users accepts a vendor_token — a token your backend issues for a
user, so a Custom API connector can call your API as them.
Rotating a token supersedes the previous one in the token history, which stores
a fingerprint only — never the recoverable secret. A freshly pushed token is
marked valid but unverified, so it is re-checked against your API on the next
agent request. That is what stops a token you have already revoked staying
valid inside Peeve.
A token authenticates; it does not authorize. Possession of one is full
account authority, so the capability allowlist you configure — not the token —
is what stands between a leaked token and real damage.