Skip to main content

​
Overview

The Event Tracking section provides real-time monitoring of all authentication events in your Better Auth application. Track user sign-ups, logins, password changes, OAuth flows, organization activities, and more.
Event tracking is only available in self-hosted mode and requires configuration in your studio.config.ts.

​
Setup

Enable event tracking in your Studio configuration:

​
Configuration

import type { StudioConfig } from 'better-auth-studio';
import { auth } from './lib/auth';
import { prisma } from './lib/prisma'; // or your database client

const config: StudioConfig = {
  auth,
  basePath: '/api/studio',
  events: {
    enabled: true,
    client: prisma,
    clientType: 'prisma', // or 'drizzle'
    tableName: 'auth_events',
  }
};

export default config;

​
Database Migration

After enabling events, run your database migration: 
# Prisma
npx prisma migrate dev --name add_auth_events

# Drizzle
npx drizzle-kit push
Events are not available in the cloud hosted version - only self-hosted deployments.

​
Event Types

Better Auth Studio tracks these event categories:

​
User Events

user.joined

New user registration

user.logged_in

Successful sign-in

user.logged_out

User logout

user.updated

Profile update

user.email_verified

Email verification completed

user.password_changed

Password update

user.banned

User banned (admin plugin)

user.unbanned

Ban removed

user.deleted

Account deletion

​
Organization Events

organization.created

New organization created

organization.updated

Organization details changed

organization.deleted

Organization removed

member.added

Member joined organization

member.removed

Member left organization

member.role_changed

Member role updated

​
Team Events

team.created

New team created

team.updated

Team details modified

team.deleted

Team removed

team.member.added

Member added to team

team.member.removed

Member removed from team

​
Session & Security Events

session.created

New session established

password.reset_requested

Password reset email sent

password.reset_completed

Password successfully reset

oauth.linked

OAuth account linked

oauth.unlinked

OAuth account unlinked

oauth.sign_in

OAuth authentication

​
Invitation Events

invitation.created

Invitation sent

invitation.accepted

Invitation accepted

invitation.rejected

Invitation declined

invitation.cancelled

Invitation revoked

​
Events Dashboard

​
Overview Stats

At the top of the Events page, see real-time statistics:
  • Success Events - Total successful operations (green)
  • Failed Events - Total failures and errors (red)
  • Warning Events - Events that need attention (yellow)
  • Info Events - General informational events (blue)

​
Event Activity Grid

Visual GitHub-style contribution graph showing:
  • Last 53 weeks of event activity
  • Daily event counts - Hover to see details
  • Color intensity - More events = darker shade
  • Click a cell - See events for that specific day
  • Category breakdown - Events grouped by type (User, Organization, Team, etc.)
The activity grid is hidden on mobile devices and visible on desktop/tablet screens.

​
Activity Details Panel

When you click a day in the activity grid:
  1. Total events for selected day
  2. Status breakdown - Success, Failed, Warning, Info counts
  3. By category - Events grouped by:
    • User events
    • Organization events
    • Team events
    • Session events
    • OAuth events
    • Invitation events
  4. Quick filter - Click category to filter main list

​
Event Workflows

1

View Recent Events

  1. Navigate to Events page
  2. See chronological list of latest events
  3. Events auto-refresh every 2 seconds (configurable)
  4. New events appear at the top with highlight animation
2

Search Events

  1. Use search bar to find events by:
    • Event type (e.g., “user.joined”)
    • User ID
    • Event message
  2. Results update as you type
3

Filter Events

  1. Click Add Filter dropdown
  2. Choose filter type:
    • Event Type - Select specific event types
    • Timestamp - Filter by date range
  3. Configure filter criteria
  4. Apply multiple filters
  5. Click Clear all to reset
4

View Event Details

  1. Click the View icon (eye) on any event
  2. Modal shows complete event information:
    • Event ID (copyable)
    • User ID (copyable)
    • Session ID (copyable, if applicable)
    • Organization ID (copyable, if applicable)
    • IP address and location
    • User agent string
    • Full metadata
    • Timestamps

​
Event Filtering

​
By Event Type

Filter events to specific types:
1

Add Event Type Filter

Click Add Filter → Event Type
2

Select Event Categories

Choose from organized categories:
  • User - All user events
  • Organization - Organization events
  • Member - Membership events
  • Session - Session creation
  • Password - Password operations
  • OAuth - OAuth events
  • Team - Team management
  • Invitation - Invitation lifecycle
  • Phone Number - SMS events
3

Choose Specific Events

Within each category, select individual event types:
  • Check boxes to include events
  • Uncheck to exclude
  • Categories expand/collapse for easier selection

​
By Timestamp

Filter events by date range:
  1. Click Add Filter → Timestamp
  2. Select From date using calendar picker
  3. Select To date
  4. Only events within range are shown

​
Quick Filters

Use the top filter dropdown for common queries:
  • All - Show all events
  • Success - Only successful events
  • Failed - Only failed events
  • Info - Informational events
  • Warning - Events with warnings

​
Event List

​
Event Display

Each event shows:
  • Event Icon - Visual indicator of event type:
    • User icon for user events
    • Building icon for organizations
    • Lock icon for security events
    • Check for success, X for failures
  • Event Type - e.g., user.logged_in
  • Event Message - Human-readable description
  • Timestamp - Precise date and time (with milliseconds)
  • Status Badge - Success (green), Failed (red), Warning (yellow), Info (blue)

​
Sorting

Sort events by timestamp:
  • Newest First (default) - Most recent at top
  • Oldest First - Chronological order
Click the sort button in the “Timestamp” column header.

​
Real-time Updates

Events update automatically:
  • Polling interval - Checks for new events every 2 seconds (configurable)
  • New event animation - Highlighted with subtle flash
  • Auto-scroll disabled - Stay on current position
  • Manual refresh - Reload page to force update
Configure polling interval in your studio.config.ts:
{
  liveMarquee: {
    pollInterval: 3000 // milliseconds
  }
}

​
Event Details Modal

Click View on any event to see comprehensive details:
  • Event ID - Unique identifier (copyable)
  • Event Type - Full event type string
  • Status - Success, Failed, Warning, or Info
  • Message - Detailed event description
  • Timestamp - Creation date/time
  • User ID - Associated user (copyable)
  • Session ID - Related session (copyable)
  • Organization ID - If organization event (copyable)
  • IP Address - Client IP with geolocation
  • Location - City, Region, Country with flag
  • User Agent - Browser and device information
  • Source - API or App origin
  • Custom Fields - Event-specific data
  • Error Details - If event failed
  • Previous Values - For update events
  • Additional Context - Extra information

​
IP Geolocation in Events

When IP geolocation is configured (see Session Management), events show:
  • IP Address - Source IP for the event
  • Geographic Location - Resolved city, region, country
  • Country Flag - Visual identifier
IP resolution is asynchronous. You may see “Resolving…” briefly while location is fetched.

​
Load More Events

Events are loaded in batches:
  1. Initial load shows 50 most recent events
  2. Scroll to bottom to see Load More button
  3. Click to fetch next 50 events
  4. Repeat to load historical events
  5. Maximum 500 events loaded in UI at once
Loading many events can impact performance. Use filters to narrow results.

​
Best Practices

1

Monitor Failed Events

  • Filter to “Failed” status daily
  • Investigate patterns in failures
  • Alert on critical failures (e.g., login failures)
2

Track User Activity

  • Use event grid to see activity trends
  • Identify peak usage times
  • Detect unusual activity spikes
3

Audit Security Events

  • Monitor password changes
  • Track OAuth linking/unlinking
  • Watch for suspicious IPs
  • Review session creation patterns
4

Organization Monitoring

  • Track organization growth
  • Monitor member changes
  • Review invitation acceptance rates
5

Clean Old Events

  • Set up periodic cleanup of old events
  • Archive events beyond retention period
  • Balance storage vs. audit needs

​
Event Retention

Consider your event retention strategy:
  • Short-term (7-30 days) - Recent activity, debugging
  • Medium-term (3-6 months) - Compliance, analytics
  • Long-term (1+ years) - Legal requirements, historical analysis
Implement automatic cleanup in your application:
DELETE FROM auth_events 
WHERE timestamp < NOW() - INTERVAL '90 days';

​
Troubleshooting

Check event configuration:
  1. Verify events.enabled: true in studio.config.ts
  2. Confirm database client and table name are correct
  3. Run migrations to create events table
  4. Check database permissions
  5. Verify self-hosted deployment (events don’t work in cloud mode)
Event tracking is only available in self-hosted mode. You’ll see a setup message explaining this limitation.
  • Check browser console for WebSocket errors
  • Verify polling interval configuration
  • Ensure network allows API polling
  • Try manual page refresh
  • Configure ipAddress provider in studio config
  • Verify API token (for IPInfo)
  • Check API rate limits
  • See IP Geolocation setup
  • Use filters to reduce event count
  • Limit time range with timestamp filter
  • Filter by specific event types
  • Consider database indexing on timestamp and type columns

​
API Reference

Event operations use these endpoints:
  • GET /api/events - List events with pagination
  • GET /api/events/count - Get event counts and statistics
  • GET /api/events/status - Check if events are enabled
  • POST /api/geo/resolve - Resolve IP to location

Build docs developers (and LLMs) love

Get started for freeTalk to us