# 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: the Sypnia engine (open source, self-hosted) and Sypnia Cloud (paid service). Status: at launch.  
Source: https://docs.sypnia.com/sdks/identifying-people/

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.

> **In plain words**
>
> Without `identify()`, Sypnia knows that a browser had a problem. With it, Sypnia knows that Ada had a problem, because your app said «this browser is Ada». Sypnia never finds out who someone is by itself.

## The call

`src/auth.ts`

```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);
```

| Field          | Type     | Required                       | Limit               | Meaning                                                                                                           |
| -------------- | -------- | ------------------------------ | ------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `person.id`    | `string` | yes                            | 1 to 128 characters | The person's id **in your app**. Sypnia treats it as an opaque string: a number as text, a UUID, anything stable. |
| `person.name`  | `string` | no                             | 120 characters      | Shown next to the person. Personal data.                                                                          |
| `person.email` | `string` | no                             | 254 characters      | Shown next to the person, and searchable. Personal data.                                                          |
| `account.id`   | `string` | no (yes if you pass `account`) | 1 to 128 characters | The id of the account the person belongs to in your app: a team, a company, a club, a shop.                       |
| `account.name` | `string` | no                             | 120 characters      | Shown 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

| Situation                               | What Sypnia does                                                               |
| --------------------------------------- | ------------------------------------------------------------------------------ |
| Nobody identified                       | The 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 laptop | Two 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`

```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](https://docs.sypnia.com/sdks/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:

- They are stored with the person, shown in the app and the Console, returned by the [API](https://docs.sypnia.com/api/sessions-and-replays), and searchable.
- They are listed as personal data in [What is collected](https://docs.sypnia.com/privacy/what-is-collected).
- The agent uses counts of people, not their names. See [Models and what is sent](https://docs.sypnia.com/agent/models-and-what-is-sent).
- You can delete one person and everything tied to them. See [Deleting data](https://docs.sypnia.com/privacy/deleting-data).

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](https://docs.sypnia.com/sdks/sampling-and-quotas#always-record-a-person-or-an-account).

## 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
