Docs

Identifying people

How identify() ties sessions and problems to a person and an account, what is stored, how anonymous sessions work, and how to identify requests on the server.

Applies to EngineCloud At launch

View as Markdown
On this page
  1. The call
  2. What happens after the call
  3. Sessions and people
  4. On the server
  5. Personal data: what you decide
  6. Always record someone
  7. Who may send an identity
  8. Check that it works
  9. Next

This page is for whoever wires Sypnia to an app’s sign-in. identify() is the same call in @sypnia/browser, @sypnia/next and @sypnia/node, and it works the same for the open-source engine and for Sypnia Cloud.

At the end you will have: problems that say who they hit («3 people», and which three), sessions you can find by person, and activity for each person and each account.

The call

src/auth.ts
import { identify } from '@sypnia/browser';

// when someone signs in, and when the app loads with someone already signed in
identify({
  person: { id: 'u_1042', name: 'Ada Park', email: 'ada@example.com' },
  account: { id: 'acc_77', name: 'Corner Café' },
});

// when they sign out
identify(null);
FieldTypeRequiredLimitMeaning
person.idstringyes1 to 128 charactersThe person’s id in your app. Sypnia treats it as an opaque string: a number as text, a UUID, anything stable.
person.namestringno120 charactersShown next to the person. Personal data.
person.emailstringno254 charactersShown next to the person, and searchable. Personal data.
account.idstringno (yes if you pass account)1 to 128 charactersThe id of the account the person belongs to in your app: a team, a company, a club, a shop.
account.namestringno120 charactersShown next to the account.

Use the id your database uses, not the e-mail: an e-mail changes, and it would put personal data into every event. An id that is not a string is turned into one. An empty or missing person.id makes the call do nothing, with one warning.

What happens after the call

  1. The SDK sends one identify event with the person and the account as you gave them. It is the only event that carries a name or an e-mail.
  2. Every later event of the session carries the two ids only: "person": {"id": "u_1042"}, "account": {"id": "acc_77"}.
  3. The session, including what happened in it before the call, belongs to that person. Someone who browses, then signs in, has one session.
  4. The SDK remembers the ids for the life of the page only. It does not store them in the browser: call identify() again on every page load where someone is signed in.

Calling it again with the same person is free: nothing is sent unless the name, the e-mail or the account changed.

Sessions and people

SituationWhat Sypnia does
Nobody identifiedThe session is anonymous. It is listed, counted and replayable like any other.
Anonymous, then identify(A)The same session, now A’s.
identify(A), then identify(null)A’s session ends. The next activity starts a new, anonymous session.
identify(A), then identify(B)A’s session ends. B’s first activity starts a new session.
The same person on a phone and a laptopTwo sessions, one person.

When Sypnia says «3 people», it counts identified persons, plus one for each device whose sessions were never identified.

On the server

Requests that come from an identified browser session need nothing: the browser SDK sends the session’s id with each call to your API, and Sypnia takes the person from the session.

Identify on the server only what no browser session identifies: calls from a mobile app, from an API client, from a webhook.

src/auth-middleware.ts
import { identify } from '@sypnia/node';

app.use((req, res, next) => {
  if (req.user) identify({ person: { id: req.user.id }, account: { id: req.user.accountId } });
  next();
});

On the server identify() applies to the request being handled and to nothing else. Names and e-mails passed here are stored the same way as from the browser.

Backends that report through OpenTelemetry cannot identify people at launch: their traces get the person from the session.

Personal data: what you decide

person.id and account.id are the only things Sypnia needs. With ids alone, Sypnia holds no name and no e-mail, and you look people up in your own system.

If you send names and e-mails:

Sending a new name or e-mail for the same person.id replaces the old one.

Always record someone

To record every session of one person or one account, for example a customer who reports a bug you cannot reproduce, add an «always record» rule to the project. It is a project setting, not code, so it takes effect at that person’s next session without a deploy. See Sampling and quotas.

Who may send an identity

At launch the ingest key is the only credential for sending, as with any browser SDK. It is public, so Sypnia cannot prove that an event saying «I am u_1042» comes from u_1042’s browser: someone who reads your page’s source could send events with any id. They could not read anything, and limits per key and allowed origins bound what they can send. Do not use Sypnia’s person data as proof of who did something.

A signed identity, for apps that need that proof, is Planned.

Check that it works

  1. Set debug: true, sign in to your app, and look at the console: one identify event, then events carrying person: { id: … }.
  2. Within 10 minutes the session in Sypnia shows the person’s name, or their id if you sent no name.

Next

Sections

Start hereWhat Sypnia is, how it works, what is open source and what is the paid cloud, and the two ways to get your first problem in plain words.ConceptsThe ten ideas Sypnia is made of, each defined precisely, from a project and its keys to problems, traces and alerts.SDKsHow your app sends data to Sypnia. One SDK for the browser, one for Node, one for Next.js, and the OpenTelemetry intake for every other backend.The agentHow Sypnia analyses a problem, what it writes, what it sends to a model and what it never does.MCP and skillsConnect your coding agent to Sypnia so it can ask what is failing in production, read what it needs to fix it, and set Sypnia up for you.API referenceThe Sypnia HTTP API: one API for the open-source engine and for Sypnia Cloud, with every endpoint, parameter, response and error.CLI referenceThe sypnia command: how to install it, the variables it reads, what its exit codes mean, and where each command is documented.Self-hostingWhat you run when you host the Sypnia engine yourself, what you need, what it costs, and what you do not get compared with Sypnia Cloud.How the engine is builtThe whole Sypnia engine on one page, from a click in your app to the sentence your coding agent reads, with the design rules and the code that holds them.Sypnia CloudHow the paid service works, from organizations and roles to plans, limits, billing, where your data lives, the GitHub App and support.Privacy and securityWhat Sypnia collects from your app and its users, what it never collects, how masking works, how to delete data, and how the service is protected.LicensingWhich licence covers each part of Sypnia, what you may do with it, how the name may be used, and the terms of a contribution.GuidesStep-by-step recipes for the common ways to use Sypnia, from apps made with AI builders and Next.js on Vercel to Supabase, source maps in CI, alert e-mails from your own engine, and moving from Sentry.ReferenceThe pages you look things up in, from the event schema and the glossary to what is planned, the changelog and the common questions.
↑↓ to move↵ to openEsc to close