Browse documentation
Documentation/API reference

API reference

Configuration options, response types and server methods.

These docs cover the Doorman 0.13 integration. Start with add Doorman to your app for a complete example. You need one server handler and one browser client.

Server setup

Import createDoorman from @aarondovturkel/doorman-adapters/node or /vercel:

const doorman = createDoorman({
  db, // Your Postgres pool.
  secret: process.env.DOORMAN_IDENTITY_SECRET!,
  namespace: "my-app",
  evaluator: false,
});

For Cloudflare, use the /cloudflare import with db: env.VISITORS and optional ai: env.AI. For Phoenix, use the native Elixir API.

Reuse the handler across requests. Tables are created automatically; the database must exist and allow schema creation. Keep the secret and namespace stable.

Server methods

Method Use
handle(request, { auth? }) Return public identity JSON and cookies.
assess(request, context?) Return that response plus private identity, account context and analytics properties.
ready() Optionally prepare tables before accepting traffic. First database use also prepares them.
cleanup(options?) Remove expired history in bounded batches.
forgetUser(rawUserId) Erase a user’s remembered relationships and dependent login feedback.
deleteVisitor(visitorId) Erase a browser and its relationships.

Pass authentication from your server, never from the browser payload:

const result = await doorman.assess(request, {
  auth: {
    userId: String(currentUser.id),
    accountId: String(currentAccount.id), // Omit without workspaces.
    // actor: { id: agent.id, kind: "agent" }, // Only after verifying its permission.
  },
});

// result.context: authenticated / remembered / inferred / ambiguous / unknown
// result.identity: browser matching, risk and optional activity scores
// result.properties: flat properties for your server analytics event
return result.response;

Omit auth for anonymous visits. A validation or database failure can leave private results absent; check result.response.ok before using them. Return only result.response to the browser.

Additional trusted context accepts riskEvidence, an explicitly resolved clientIp for optional reputation, admission keys for request quotas, and learningConsent: false to withdraw login-feedback collection for that session. See identity context and limits.

Common server options

Option Default or behavior
evaluator Node/Vercel: disabled unless configured; { apiKey } enables Jev. Cloudflare uses ai.
evaluatorTimeoutMs Short bounded deadline; see Jev and inference limits.
crossDevice false; opt into confirmed login feedback and private suggestions.
classifyOperator true in the recommended API; needs an evaluator and enough activity evidence.
scoring Optional TypeScript browser similarity and confidence weights.
activity Off; configure route templates to enable request aggregates.
reputation Off; requires provider credentials and a trusted client IP.
observationRetentionDays 90.
maxObservationsPerVisitor 10; matching reads at most five recent observations.
cookie __visitor, Secure, HttpOnly, SameSite=Lax, Path=/.
maxInFlightRequests 64 per reusable TypeScript handler.
protection Shared database request and evaluator limits; configuration.
autoMigrate true; leave on for normal installation.

The recommended flow always keeps scores private, disables AI lookup planning and creates a fresh browser ID when a usable cookie is missing. A possible previous-browser match remains private evidence; it does not restore a guessed identity or merge analytics profiles.

Browser setup

import { createDoormanClient } from "@aarondovturkel/doorman-browser";

const doorman = createDoormanClient({
  endpoint: "/api/visitor",
  analytics: { posthog, mixpanel }, // Optional initialized SDKs.
  collection: "minimal", // Default; "extended" adds optional summaries.
});

The endpoint must be on your application’s origin. headers can supply a Phoenix CSRF token. enabled: false delays collection until setEnabled(true).

Method Use
identify() Measure an anonymous browser.
identify(userId, traits?) Identify after your app verifies login, then measure the browser.
identify({ userId, accountId? }, traits?) The same, with workspace context.
update({ name?, email?, plan? }) Update the current identified user’s profile.
track(event, properties?) Optional forwarding to connected analytics SDKs. Do not also track that event directly.
reset() Reset analytics identity and local measurement state after logout or user switching.
setEnabled(boolean) Pause or resume Doorman collection.
destroy() Remove listeners and discard pending measurements. Create a new client after teardown.

The public identification result is { visitorId, sessionId, isReturning }. Calls can reject on network, request or storage failure; catch measurement errors so they do not break login or navigation. reset() does not log the user out or delete the HttpOnly cookie.

Existing PostHog/Mixpanel events can stay. See the analytics guide for the optional tracking helper, identity lifecycle and other providers. Doorman does not enable session replay, capture application logs or configure analytics dashboards.

Search documentation

Search setup instructions, examples and the API reference.

Local search. No query leaves your browser.