Dashboard

The Dashboard plugin is the core connection between your Better Auth instance and Better Auth Infrastructure. It powers the web dashboard with real-time data, tracks user activity, and enables admin APIs.

What the Dashboard Plugin Enables

Once dash() is active, the Better Auth Infrastructure dashboard gives you:

• User management — view, search, ban, and delete users
• Session monitoring — see active sessions and revoke them
• Organization overview — manage organizations and members
• Analytics — track sign-ups, sign-ins, and active users over time
• Audit logs — query event history (learn more)

Installation

import { betterAuth } from "better-auth";
import { dash } from "@better-auth/infra";

export const auth = betterAuth({
  plugins: [
    dash(),
  ],
});

Compatibility

@better-auth/infra requires Better Auth 1.4 or later. Actively supported @better-auth/infra releases start at 0.3.

Use the latest 0.4.x release with the latest stable Better Auth 1.7.x.

Configuration Options

DashOptions

Activity Tracking

Track when users were last active in your application. When enabled, a lastActiveAt field is automatically updated on user activity.

dash({
  apiKey: process.env.BETTER_AUTH_API_KEY,
  activityTracking: {
    enabled: true,
    updateInterval: 300000,  // Update interval in ms (default: 5 minutes)
  },
}),

Schema Changes

When activity tracking is enabled, the plugin adds a field to your user schema:

user: {
  fields: {
    lastActiveAt: {
      type: "date",
    },
  },
}

npx auth@latest migrate

If your app manages schema generation separately, run npx auth@latest generate and apply the generated migration with your preferred tool.

Managed Directory Sync

Managed directory sync is the dashboard-side companion to the SCIM plugin-managed connections. Use it when each organization (tenant) should get a directory connection from the dashboard — without hard-coding every tenant in application config.

In Better Auth 1.7, SCIM supports three connection modes:

• static code-defined connections
• application-owned runtime verification
• plugin-managed runtime connections via managedConnections

Managed directory sync is built for that third mode. Responsibilities split cleanly:

Once the control plane is on, you can layer optional behaviors: project users into organization memberships and pair the directory with SSO for sign-in, map SCIM attributes onto custom fields.

Enable managed directory sync

You need the organization, SCIM, and dash plugins. SCIM must use managedConnections so Infrastructure can reserve and issue per-tenant credentials.

import { betterAuth } from "better-auth";
import { organization } from "better-auth/plugins";
import { sso } from "@better-auth/sso";
import { scim } from "@better-auth/scim";
import { dash } from "@better-auth/infra";

export const auth = betterAuth({
  plugins: [
    organization(),
    sso({}),
    scim({
      connections: [],
      managedConnections: {
        credentialHashSecret: process.env.SCIM_CREDENTIAL_HASH_SECRET!,
      },
    }),
    dash({
      apiKey: process.env.BETTER_AUTH_API_KEY,
      managedDirectorySync: {
        enabled: true,
      },
    }),
  ],
});

npx auth@latest migrate

If your app manages schema generation separately, run npx auth@latest generate and apply the generated migration with your preferred tool.

After setup, create and manage directories in the Infrastructure dashboard (or via the directory sync endpoints).

Membership projection

Membership projection is the usual next step after a directory is connected: when SCIM provisions or deactivates a user, dash reconciles that user into the organization that owns the directory.

It is enabled by default whenever managed directory sync is on.

dash({
  apiKey: process.env.BETTER_AUTH_API_KEY,
  managedDirectorySync: {
    enabled: true,
    membershipProjection: {
      enabled: true,
      role: "member", // role only when projection creates the membership
    },
  },
})

Behavior:

• Active directory users are added to the organization (or linked if they are already members).
• Deactivated users have directory-owned memberships removed.
• Provenance tracks whether the membership was created by the directory or only observed (already existed). Projection only mutates memberships it owns.

Turn it off only when SCIM should provision users without touching organization membership:

membershipProjection: {
  enabled: false,
}

SSO pairing

SSO pairing links a managed directory to an SSO provider so a provisioned user can sign in with the same identity the directory manages.

It is enabled by default. You only need it when directories are created as paired with SSO.

plugins: [
  sso({}),
  dash({
    apiKey: process.env.BETTER_AUTH_API_KEY,
    managedDirectorySync: {
      enabled: true,
      ssoPairing: true,
    },
  }),
]

Notes:

• Paired sign-in resolves the Better Auth user from the SCIM external id configured on the directory.
• Set ssoPairing: false when you only need provisioning and never create paired directories.

Field projection

Field projection maps SCIM User attributes onto Better Auth fields during directory-sync reconcile. Mappings are configured per directory connection in the Infrastructure dashboard (or via the field-mapping endpoints).

It is opt-in and adds its own tables — enable it, migrate, then configure mappings.

import { betterAuth } from "better-auth";
import { organization } from "better-auth/plugins";
import { scim } from "@better-auth/scim";
import { dash } from "@better-auth/infra";

export const auth = betterAuth({
  user: {
    additionalFields: {
      employeeId: { type: "string", required: false },
      department: { type: "string", required: false },
    },
  },
  plugins: [
    organization({
      schema: {
        member: {
          additionalFields: {
            title: { type: "string", required: false },
            costCenter: { type: "string", required: false },
          },
        },
      },
    }),
    scim({
      connections: [],
      managedConnections: {
        credentialHashSecret: process.env.SCIM_CREDENTIAL_HASH_SECRET!,
      },
    }),
    dash({
      apiKey: process.env.BETTER_AUTH_API_KEY,
      managedDirectorySync: {
        enabled: true,
        fieldProjection: {
          enabled: true,
        },
      },
    }),
  ],
});

1. Declare the user / member fields you want to fill (as above).
2. Run migrations for the field-mapping tables.
3. In the Infrastructure dashboard, open the directory connection and map SCIM paths → target fields.

Projectable fields

Only directory-created memberships (ownership: "created") receive member field projection. Observed memberships are left unchanged.

SCIM attribute catalog

Mappings read from a curated SCIM User attribute catalog:

Values are resolved as strings from the persisted SCIM user row, then coerced to the Better Auth field type (string, number, boolean, or date).

Projection modes

Each connection stores a mode per entity (user and member). Default mode is create-only.

Options reference

Full managedDirectorySync shape:

Database schema

When managedDirectorySync.enabled is true, the dash plugin adds the models below. Better Auth supplies the primary id field for each model. Some tables are only installed when an opt-in feature is enabled.

directorySyncConnection

Always present when managed directory sync is enabled. Stores the managed directory's organization, SCIM connection, SSO pairing, lifecycle, and decommission state.

directorySyncMembershipProvenance

Always present when managed directory sync is enabled. Tracks organization memberships created or managed by membership projection.

directorySyncFieldMapping

Only when fieldProjection.enabled is true. Per-connection mapping from SCIM attributes (and/or static defaults) onto Better Auth fields.

directorySyncFieldProjectionMode

Only when fieldProjection.enabled is true. Per-connection, per-entity write cadence (create-only or reconcile).

directorySyncFieldProvenance

Only when fieldProjection.enabled is true. Marks that create-only fields were applied for a provisioning domain + entity + target row.

For the full SCIM model and migration guidance, see the SCIM plugin reference and the 1.7 upgrade guide.

Event Tracking

The dash plugin automatically tracks the following events:

User Events

Session Events

Account Events

Verification Events

Organization Events

If you're using the organization plugin, these events are also tracked:

Dashboard Endpoints

The dash plugin registers numerous admin endpoints for the dashboard:

Config

User Management

Session Management

Organization Management

Team Management

Invitation Management

SSO Management

Directory Sync

Events & Audit Logs

Analytics

Two-Factor Management

Client Integration

dashClient()

The client plugin provides access to audit log queries:

import { createAuthClient } from "better-auth/client";
import { dashClient } from "@better-auth/infra/client";

export const authClient = createAuthClient({
  plugins: [dashClient()],
});

Note: For Expo or React Native, import dashClient from @better-auth/infra/native (same API) and pair it with sentinelNativeClient as described in Sentinel — Expo and React Native.

Configuration

dashClient({
  resolveUserId: ({ userId, user, session }) => {
    return userId || user?.id || session?.user?.id;
  },
}),

Get the current user's audit logs

Returns audit events for the current user, or organization-scoped events when you pass organizationId as a member.

Basic query

const session = await authClient.getSession();

const logs = await authClient.dash.getAuditLogs({
  session: session.data,
  limit: 50,
  offset: 0,
});

// Access the data
console.log(logs.data?.events);  // Array of audit log events
console.log(logs.data?.total);   // Total count
console.log(logs.data?.limit);   // Page size
console.log(logs.data?.offset);  // Current offset

See Get current user's audit logs for more information.

Get all audit logs

Returns all audit events for organizations the current user has admin or owner access to. Requires the organization plugin for role checks.

Basic query

const session = await authClient.getSession();

const activity = await authClient.dash.getAllAuditLogs({
  session: session.data,
  limit: 50,
  offset: 0,
});

console.log(activity.data?.events);
console.log(activity.data?.total);

See Get all audit logs for more information.

Best Practices

1. Always set an API key — without it, the plugin cannot communicate with the infrastructure API.

2. Use activity tracking wisely — the update interval affects database writes. For high-traffic apps, consider a longer interval.

3. Monitor audit log retention — different plans have different retention periods. Check your plan limits.

4. Secure your endpoints — dashboard endpoints require authentication. Make sure your dashboard users have appropriate permissions.