# Identify signed-in users

Does your site have a signed-in area? Its server can tell the pixel who is signed in. In **Live**, instead of "Visitor #a3f2", the person's name shows up, with a verified badge.

Each identification is signed with the business's **identification key**, so nobody can pretend to be one of your customers.

## The identification key

It's in **Business settings → Pixel → Identify signed-in users**. Viewing the key requires the **Manage API keys** permission.

::: danger Keep the key on the server only
Treat the key like a password. Never put it in your site's HTML or JavaScript: anyone with the key can show up in Live as any of your customers.
:::

## How it works

On every signed-in page, after the pixel snippet, the server:

1. Builds a JWT with the **HS256** algorithm, signed with the identification key.
2. Writes an `ls("identify", "<jwt>")` call on the page.

Any JWT library with HS256 works.

## Accepted fields

| Field | Required | Format |
|---|---|---|
| `sub` | yes | The person's id in your system, up to 128 characters. |
| `name` | no | Up to 120 characters. |
| `email` | no | Email. |
| `phone` | no | 8 to 15 digits, with an optional country `+`. |
| `exp` | no | Expiry, in Unix seconds. |

Any other field is ignored.

## PHP example, no library

```php
$b64 = fn($data) => rtrim(strtr(base64_encode($data), '+/', '-_'), '=');
$header = $b64(json_encode(['alg' => 'HS256', 'typ' => 'JWT']));
$payload = $b64(json_encode([
    'sub' => (string)$user['id'],
    'name' => $user['name'],
    'email' => $user['email'],
    'phone' => $user['phone'],
    'exp' => time() + 86400,
]));
$jwt = "$header.$payload." . $b64(hash_hmac('sha256', "$header.$payload", LEADSTALKER_IDENTITY_SECRET, true));

echo '<script>ls("identify", "' . $jwt . '");</script>';
```

`LEADSTALKER_IDENTITY_SECRET` is a constant on your server holding the identification key.

## Rules

- Sign on the server, where the key lives.
- An accepted field in the wrong format is dropped, but the identification still counts with the others.
- A token whose signature doesn't match, or that has expired (`exp`), doesn't identify: the person shows up only as a known lead.
- Call it on every signed-in page. People who aren't signed in don't need identification: they stay visitors.
- Email and phone only show up in Live for people with the **View contact details** permission in the business.
