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. Scoring, alerting, badging, and webhook notifications all revolve around them.

What Is an Identity

Dregs creates an identity the first time you call dregs.identify() with a given ID. The identifier you pass — 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, Dregs associates all events from the current session with this identity and links the device fingerprint to it.

Choose your identity IDs carefully. Use whatever identifier is stable and unique in your system. Users who change their email will appear as new identities, so 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 for display in the dashboard. These appear in the identities list and detail views so you can recognize users at a glance without digging through raw data.

Dregs stores all other fields as metadata on the identity. Pass anything useful for your analysis: plan tier, company name, referral source, account role, or any custom field relevant to your application.

How Identities Accumulate Data

An identity is no static record. It is 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 or device the user visits from links to the identity via its fingerprint. A single user accessing your app from a laptop and a phone will have two devices on 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 — contribute to behavioral scoring.

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

Scores

Dregs scores every identity 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 sees their scores adjust in real time. For a full explanation of how Dregs calculates each score, 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.

The identity detail page in the dashboard shows these relationships. 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 proves 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

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

Badge rules trigger 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 ride along in webhook payloads, supporting both human review and automated responses. For more on configuring badge rules, see Badges.

Disregarding Identities

Some identities should never be scored. Mark your own team members, test accounts, and known-good users as "disregarded" to exclude them from analysis entirely.

Disregarding an identity does two things:

1. Skips scoring — Dregs no longer scores the identity and skips alert and badge evaluation for it.
2. Excludes associated devices — Dregs excludes any devices linked to the disregarded identity when scoring other identities. This prevents your team's shared office devices from dragging down the Uniqueness scores of legitimate users on the same network.

You can toggle the disregarded status from the identity detail page in the dashboard. After you toggle it, Dregs automatically re-queues affected identities 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, and confidence grows with data volume.
4. Alerts triggered — Configured alert rules evaluate after each scoring update. When thresholds are crossed, Dregs notifies your team through the channels you've set up.
5. Badges applied — Badge rules settle after scoring. Identities gain or lose badges as their scores change, giving a quick visual classification in the dashboard and in webhook payloads.

The lifecycle has no end. As long as an identity keeps generating events, Dregs keeps scoring. Inactive identities retain their last known scores and undergo periodic re-evaluation for accuracy.