Browse documentation
Documentation/Browsers, people & agents

Browsers, people & agents

The different identities in your app, explained with one example.

These concepts apply to your Go application. Matching and private risk evaluation run in your application-owned TypeScript or Elixir engine; this client handles the HTTP connection. See your setup guide. Code labeled TypeScript describes the engine configuration.

Doorman keeps a few kinds of identity separate. Understanding the difference will help you choose the right ID for a browser, a user profile or an account report.

One example, three IDs

Alex and Sam work in a shared design workspace. Alex uses a laptop and a phone, and has given an AI assistant permission to read the workspace calendar.

Thing you want to identify Example What identifies it
A browser Alex’s laptop browser Doorman’s visitorId
A person or agent Alex, Sam, or Alex’s assistant A verified identity registered by your server
A shared workspace The design studio Your application’s existing account or workspace ID

Alex’s phone gets its own browser ID. It can still belong to the same signed-in user. If Sam borrows Alex’s laptop, the browser ID can stay the same while the user changes.

Visitor

A visitor is a browser environment with a stored history. Doorman assigns it an opaque, random ID beginning with vis_. A cookie usually preserves that ID. When the cookie is missing, Doorman issues a fresh ID and keeps any possible historical match private.

isReturning means Doorman found an existing visitor record. It does not mean the current user has an account, is authenticated, or is the same person who used the browser previously.

Session

A session groups recent browser assessments under sessionId. It expires after 30 minutes between assessments. It does not sign anyone in and is separate from your application’s authenticated session.

Observation

An observation is a small snapshot of browser signals, such as browser family, language, screen size and timezone. All fields are optional. A visitor has several recent observations, which lets Doorman tolerate ordinary changes.

Doorman stores observations in your database. They are never encoded into the visitor ID. See the signal inventory.

Subject and actor

In the identity API, a subject is a registered person or agent. The recommended auth integration registers it automatically after your server supplies a verified user or agent. You do not need a separate directory call for ordinary logins.

For a particular request, the subject is the identity being represented and the actor is the person or agent making the request:

Request Subject Actor
Alex opens their calendar Alex Alex
Alex’s assistant reads that calendar Alex Alex’s assistant
Sam uses permission Alex granted Alex Sam

An actor is not inferred from a low automation score. If your server has not established who is acting, Doorman reports the actor as unknown.

Agent permission

Your application verifies whether an agent may act for a user, which actions it may perform and when that permission expires. Pass its verified identity through auth.actor after those checks. Doorman records identity context; activity scores cannot grant permission.

Confidence and risk

Confidence describes browser continuity. Cookie-based continuity returns 1. A new browser ID returns 0; possible previous-browser matches carry their own private comparison score. These values do not measure how trustworthy a person is.

Risk describes technical evidence from the current visit:

  • automation: how consistent the available evidence is with browser automation.
  • suspicious: how inconsistent or unusual the technical signals look.

These are separate scores. An authorized AI assistant can be automated. A familiar browser can be compromised. Always check riskStatus: a zero returned when evaluation is disabled or unavailable is not an assessment of safety.

Which ID should analytics use?

Use your authenticated user ID to identify a person in PostHog or Mixpanel. Use your workspace ID to group shared-account activity. Keep Doorman’s visitor ID as browser context rather than replacing a person’s analytics identity with it.

The analytics guide shows login, user switching, logout and reports. The integration guide shows how to pass verified users and agents.

Search documentation

Search setup instructions, examples and the API reference.

Local search. No query leaves your browser.