Dashboard Plugin (dash)

The `dash()` plugin connects your Better Auth instance to Better Auth Infrastructure, enabling analytics tracking, event logging, and admin dashboard APIs.

Installation

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

export const auth = betterAuth({
  plugins: [
    dash({
      apiUrl: process.env.BETTER_AUTH_API_URL,
      kvUrl: process.env.BETTER_AUTH_KV_URL,
      apiKey: process.env.BETTER_AUTH_API_KEY,
    }),
  ],
});

Configuration Options

DashOptions

OptionTypeDescription
apiUrlstringBetter Auth Infrastructure API URL
kvUrlstringKV store URL for caching
apiKeystringYour API key for authentication
apiTimeoutnumberTimeout in ms for infra API HTTP requests (apiUrl). Default: 3000
kvTimeoutnumberTimeout in ms for KV HTTP requests (kvUrl). Default: 1000
activityTrackingobjectActivity tracking configuration

Activity Tracking

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

When enabled, this adds a lastActiveAt field to your user schema that's automatically updated on user activity.

Event Tracking

The dash plugin automatically tracks the following events:

User Events

EventTrigger
user_signed_upNew user registration
user_profile_updatedUser updates their profile
user_profile_image_updatedUser changes their avatar
user_email_verifiedEmail verification completed
user_bannedUser is banned
user_unbannedUser is unbanned
user_deletedUser account deleted

Session Events

EventTrigger
user_signed_inSuccessful sign-in
user_signed_outUser signs out
session_createdNew session created
session_revokedSingle session revoked
sessions_revoked_allAll sessions revoked
user_impersonatedAdmin starts impersonating user
user_impersonation_stoppedAdmin stops impersonating

Account Events

EventTrigger
account_linkedSocial account linked
account_unlinkedSocial account unlinked
password_changedPassword updated

Verification Events

EventTrigger
password_reset_requestedPassword reset initiated
password_reset_completedPassword reset finished
email_verification_sentVerification email sent

Organization Events

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

EventTrigger
organization_createdNew organization created
organization_updatedOrganization settings changed
member_addedMember added to organization
member_removedMember removed from organization
member_role_updatedMember role changed
member_invitedInvitation sent
invite_acceptedInvitation accepted
invite_rejectedInvitation rejected
invite_cancelledInvitation cancelled
team_createdTeam created
team_updatedTeam updated
team_deletedTeam deleted
team_member_addedMember added to team
team_member_removedMember removed from team

Dashboard Endpoints

The dash plugin registers numerous admin endpoints for the dashboard:

User Management

EndpointMethodDescription
/dash/usersGETList users with pagination
/dash/users/online-countGETGet online users count
/dash/userGETGet user details
/dash/userPOSTCreate a new user
/dash/userPATCHUpdate user
/dash/userDELETEDelete user
/dash/user/banPOSTBan user
/dash/user/unbanPOSTUnban user
/dash/user/passwordPOSTSet user password
/dash/user/impersonatePOSTImpersonate user

Session Management

EndpointMethodDescription
/dash/sessionsGETList all sessions
/dash/sessionsDELETEDelete sessions
/dash/session/revokePOSTRevoke single session
/dash/sessions/revoke-allPOSTRevoke all user sessions

Organization Management

EndpointMethodDescription
/dash/organizationsGETList organizations
/dash/organizationGETGet organization details
/dash/organizationPOSTCreate organization
/dash/organizationPATCHUpdate organization
/dash/organizationDELETEDelete organization
/dash/organization/membersGETList members
/dash/organization/memberPOSTAdd member
/dash/organization/memberDELETERemove member
/dash/organization/member/rolePATCHUpdate member role

Team Management

EndpointMethodDescription
/dash/organization/teamsGETList teams
/dash/organization/teamPOSTCreate team
/dash/organization/teamPATCHUpdate team
/dash/organization/teamDELETEDelete team
/dash/organization/team/memberPOSTAdd team member
/dash/organization/team/memberDELETERemove team member

Invitation Management

EndpointMethodDescription
/dash/organization/invitationsGETList invitations
/dash/organization/invitePOSTSend invitation
/dash/organization/invite/cancelPOSTCancel invitation
/dash/organization/invite/resendPOSTResend invitation

SSO Management

EndpointMethodDescription
/dash/organization/sso-providersGETList SSO providers
/dash/organization/sso-providerPOSTCreate SSO provider
/dash/organization/sso-providerPATCHUpdate SSO provider
/dash/organization/sso-providerDELETEDelete SSO provider
/dash/organization/sso-provider/verify-domainPOSTVerify domain

Directory Sync

EndpointMethodDescription
/dash/organization/directoriesGETList directories
/dash/organization/directoryPOSTCreate directory
/dash/organization/directoryDELETEDelete directory
/dash/organization/directory/tokenPOSTRegenerate token

Log Drains

EndpointMethodDescription
/dash/organization/log-drainsGETList log drains
/dash/organization/log-drainPOSTCreate log drain
/dash/organization/log-drainPATCHUpdate log drain
/dash/organization/log-drainDELETEDelete log drain
/dash/organization/log-drain/testPOSTTest log drain

Events & Audit Logs

EndpointMethodDescription
/events/listGETGet user events
/events/audit-logsGETGet audit logs
/events/typesGETGet event types

Analytics

EndpointMethodDescription
/dash/statsGETGet user statistics
/dash/graphGETGet graph data
/dash/retentionGETGet retention data
/dash/mapGETGet geographic data

Two-Factor Management

EndpointMethodDescription
/dash/user/2fa/enablePOSTEnable 2FA for user
/dash/user/2fa/disablePOSTDisable 2FA for user
/dash/user/2fa/totp-uriGETGet TOTP URI
/dash/user/2fa/backup-codesGETView backup codes
/dash/user/2fa/backup-codes/generatePOSTGenerate new codes

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 }) => {
    // Custom user ID resolution logic
    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.

Schema Extensions

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

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

Make sure to run database migrations after enabling activity tracking.

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.