Identities

Every user in your system becomes an identity in Dregs — a living profile that accumulates devices, events, behavioral patterns, and risk scores over time. Identities are the central unit of analysis. Everything Dregs does — scoring, alerting, badging, webhook notifications — revolves around them.

What Is an Identity

An identity is created the first time you call dregs.identify() with a given ID. The identifier you pass — whether it's a user ID, username, or email address — becomes the identity's permanent ID in Dregs.

dregs.identify('user_12345', {
  name: 'Jane Cooper',
  email: 'jane@example.com'
});

This single call creates (or updates) an identity with ID user_12345 in Dregs. From this point forward, all events from the current session are associated with this identity, and the device fingerprint is linked to it.

Choose your identity IDs carefully. Use whatever identifier is stable and unique in your system. If you use email addresses, be aware that users who change their email will appear as new identities. Internal user IDs or UUIDs tend to be the most reliable choice.

Identity Data

The second argument to dregs.identify() is an optional data object. You can pass any key-value pairs that help describe the user.

dregs.identify('user_12345', {
  name: 'Jane Cooper',
  email: 'jane@example.com',
  plan: 'enterprise',
  company: 'Acme Inc',
  role: 'admin',
  signup_source: 'google_ads'
});

Dregs automatically extracts name and email fields for display in the dashboard. These appear in the identities list and detail views so you can quickly recognize users without digging through raw data.

All other fields are stored as metadata on the identity. You can pass anything that's useful for your analysis, such as the plan tier, company name, referral source, account role, or any custom field relevant to your application.

How Identities Accumulate Data

An identity is not a static record. It's a continuously enriched profile that grows with every interaction.

• Events — Every dregs.track() call while the user is identified adds an event to their history. Page views, form submissions, purchases, settings changes... all of it builds the behavioral profile.
• Devices — Each browser/device the user interacts from is linked to the identity via its fingerprint. A single user accessing your app from a laptop and a phone will have two devices associated with their identity.
• Sessions — Dregs tracks individual sessions within each device. Session velocity, duration, and frequency all factor into scoring.
• IP Addresses — The server captures the IP address of each event. IP patterns (stability, geolocation, VPN usage, etc) contribute to behavioral scoring.

The more data an identity accumulates, the more confident Dregs becomes in its scores. A brand-new identity with a single event will have lower confidence than one with weeks of behavioral history.

Scores

Every identity is scored across four dimensions on a 0-100 scale:

• Humanity — Is this a real human or a bot?
• Authenticity — Is the provided data genuine or fabricated?
• Uniqueness — Is this the user's only account?
• Behavior — Does this user behave like a legitimate customer?

Scores update automatically whenever new events arrive. A user who looks fine at signup but starts behaving suspiciously will see their scores adjust in real time. For a full explanation of how each score is calculated, see Scoring.

Related Identities

Dregs automatically discovers relationships between identities. When two accounts share a device, use similar names, have overlapping email patterns, connect from the same IP, or exhibit similar behavioral signatures, Dregs links them as related identities.

Relationships are shown on the identity detail page in the dashboard. Each relationship includes a type (shared device, similar name, similar email, shared IP, shared session, similar behavior), a strength score, and an explanation of what triggered the connection.

This is particularly valuable for detecting:

• Duplicate accounts — The same person signing up multiple times with different email addresses to exploit free trials.
• Account rings — Groups of accounts operated by the same person or team, often sharing devices or behavioral patterns.
• Credential sharing — Multiple people using a single account from different devices and locations.

Badges

Badges are automatic labels applied to identities by badge rules. They classify users into categories you define — "trusted", "suspicious", "known bot", "VIP", or whatever labels make sense for your application.

Badge rules trigger based on score thresholds. For example, you might create a "likely bot" badge that activates when an identity's Humanity score drops below 20. Badges can be positive (marking good users), negative (flagging bad actors), or neutral (informational labels).

Badges appear on identity cards in the dashboard and are included in webhook payloads, making them useful for both human review and automated responses. For more on configuring badge rules, see Badges.

Disregarding Identities

Some identities shouldn't be scored at all. Your own team members, test accounts, and known-good users can be marked as "disregarded" to exclude them from analysis entirely.

Disregarding an identity does two things:

1. Skips scoring — The identity is no longer scored, and alerts and badges are not evaluated for it.
2. Excludes associated devices — Any devices linked to the disregarded identity are excluded when scoring other identities. This prevents your team's shared office devices from dragging down the Uniqueness scores of legitimate users who happen to use the same network.

You can toggle the disregarded status from the identity detail page in the dashboard. After toggling, affected identities are automatically re-queued for scoring to reflect the change.

Identity Lifecycle

An identity follows a natural progression as data accumulates:

1. Created — First dregs.identify() call. The identity appears in the dashboard with initial data but no scores yet.
2. First scored — After enough events and device data arrive, Dregs runs the scoring engine for the first time. Initial scores appear within seconds of the first events.
3. Continuously updated — Every new event triggers a scoring update. Scores rise or fall as behavior patterns emerge. Confidence increases with data volume.
4. Alerts triggered — If alert rules are configured, they evaluate after each scoring update. When thresholds are crossed, your team is notified through the channels you've set up.
5. Badges applied — Badge rules settle after scoring. Identities gain or lose badges as their scores change, providing a quick visual classification in the dashboard and in webhook payloads.

There is no "end" to the lifecycle. As long as an identity keeps generating events, Dregs keeps scoring. Identities that go inactive retain their last known scores and are periodically re-evaluated to ensure accuracy.