Skip to content

Your favorite shift management application!

12.7 KB
Raw Blame

Admin Panel Guide

This guide covers the admin panel features in BetterShift, including user management, calendar administration, and audit logging.

Table of Contents

  1. Overview
  2. Dashboard
  3. Roles and Permissions
  4. User Management
  5. Calendar Management
  6. Audit Logs
  7. Announcements
  8. Rate Limiting

Overview

The admin panel is available at /admin and provides system-wide management capabilities. Access requires authentication with an admin or superadmin role.

Accessing the Admin Panel

  1. Login with an admin account
  2. Click your profile menu in the header
  3. Select "Admin Panel"

Or navigate directly to /admin.

Navigation

  • Desktop: a sidebar on the left links to Dashboard, Users, Calendars, Audit Logs, and Announcements.
  • Phone: the same five areas are reached through a bottom tab bar instead of a sidebar.
  • Viewing or editing a single user or calendar opens as a side panel over the current list, not as a separate page — the list stays where you left it underneath.

Dashboard

Location: /admin (the page you land on when opening the admin panel)

The dashboard exists so you can tell at a glance whether anything needs attention, without opening every section.

  • Header: instance version, build date, and commit hash, with an update indicator that links to the GitHub release when a newer version is available.
  • Attention banners: shown here directly rather than buried in a section — an orphaned-calendars warning (links straight to /admin/calendars) and an available-update notice.
  • Recent Activity: admin actions and security events combined into one feed (the same entries as Audit Logs), each with a severity indicator, a plain-language description, and a relative timestamp. "View all" links to /admin/logs.
  • Scope: one list with total users (by role), total calendars (orphaned count called out separately), total shifts, active shares (by user vs. token), and events in the last 7 days — this replaced an earlier grid of separate stat cards.
  • Jump links: below Scope, direct links to Users, Calendars, and Audit Logs. On phones, use the bottom tab bar for this instead.

Roles and Permissions

BetterShift uses a three-tier role system:

Role Description Capabilities
user Standard user Manage own calendars, view shared calendars
admin Administrator View users/calendars/logs, edit regular users, reset passwords, transfer calendars
superadmin Super Administrator All admin capabilities plus: delete users, delete calendars, delete audit logs, ban/unban, role changes

Permission Matrix

Feature Superadmin Admin User
User Management
View all users Yes Yes No
Edit regular users (role: user) Yes Yes No
Edit admins/superadmins Yes No No
Delete regular users Yes No No
Ban/Unban users Yes No No
Change user roles Yes No No
Reset passwords Yes Yes No
Calendar Management
View all calendars Yes Yes No
Transfer calendar ownership Yes Yes No
Delete any calendar Yes No No
Orphaned Calendars
View orphaned calendars Yes Yes No
Assign orphaned calendars Yes Yes No
Delete orphaned calendars Yes No No
Audit Logs
View all audit logs Yes Yes No
Delete audit logs Yes No No
System Stats
View system statistics Yes Yes No

First User Promotion

The first user to register automatically becomes a superadmin. This ensures there's always an administrator who can manage the system.

Role Assignment

  • Superadmins can promote users to admin via the user management page
  • Superadmins cannot be demoted (protection against lockout)
  • Admins cannot modify other admins or superadmins

User Management

Location: /admin/users

User Table

The user table displays all registered users with:

  • Avatar, name, and email
  • Role badge (User, Admin, Superadmin)
  • Status badge (Active, Banned)
  • Registration date
  • Action menu

Available Actions

Action Admin Superadmin Description
View Details Yes Yes View user profile, calendars, and activity
Edit User Regular users only Yes Change name, email
Change Role No Yes Promote/demote user roles
Reset Password Yes Yes Generate new password for user
Ban User No Yes Temporarily or permanently ban with reason
Unban User No Yes Remove ban from user
Delete User No Yes Permanently delete user and their data

Admins can only edit users with the "user" role. They cannot modify other admins or superadmins.

Banning Users

When banning a user:

  1. Click the action menu and select "Ban User"
  2. Enter a ban reason (required)
  3. Optionally set an expiration date
  4. Confirm the ban

Banned users:

  • Cannot login (see ban reason on login page)
  • Have all sessions revoked immediately
  • Cannot access the API
  • Are automatically unbanned after expiration (if set)

Deleting Users

Deleting a user permanently removes:

  • User account and profile
  • All sessions
  • All owned calendars (including shifts, presets, notes)
  • All calendar shares they created

This action cannot be undone. A confirmation dialog requires typing the user's email.


Calendar Management

Location: /admin/calendars

Calendar Table

Displays all calendars in the system with:

  • Calendar name and color indicator
  • Owner information (or "Orphaned" badge)
  • Statistics (shifts, notes, presets, shares)
  • Guest access bundle
  • Action menu

Orphaned Calendars

Calendars without an owner (orphaned) appear at the top of the list with a red "Orphaned" badge. This happens when:

  • The calendar was created before auth was enabled
  • The owner was deleted
  • Database migration issues

Orphaned calendars are invisible to regular users and can only be managed through the admin panel.

Available Actions

Action Admin Superadmin Description
View Details Yes Yes View calendar info and statistics
Edit Calendar Yes Yes Change name, color, guest access bundle
Transfer Ownership Yes Yes Assign calendar to a different user
Delete Calendar No Yes Permanently delete calendar

Transferring Calendars

To transfer calendar ownership:

  1. Click the action menu and select "Transfer"
  2. Search for the new owner by name or email
  3. Select the user from results
  4. Confirm the transfer

The previous owner loses access (unless re-shared), and the new owner gains full control.

Bulk Operations

Superadmins can select multiple calendars for:

  • Bulk Transfer: Assign all selected calendars to one user
  • Bulk Delete: Delete all selected calendars

Use these carefully - bulk operations cannot be undone.


Audit Logs

Location: /admin/logs

The audit log tracks all significant actions in the system for security and compliance.

Logged Events

Category Events
Authentication Login, logout, registration, password change
User Management Ban, unban, delete, role change, password reset
Calendar Create, delete, transfer, share changes
Admin Actions All admin panel operations

Log Entry Details

Each log entry includes:

  • Timestamp
  • Action type
  • Actor (who performed the action)
  • Severity level (Info, Warning, Error, Critical)
  • Metadata (additional context)
  • IP address and user agent

Filtering Logs

Filter audit logs by:

  • Action type (dropdown)
  • Severity level
  • Date range
  • Search text (searches action and metadata)

Deleting Old Logs

Superadmins can delete logs older than a specified date:

  1. Click "Delete Old Logs"
  2. Select the cutoff date
  3. Review what will be deleted
  4. Confirm deletion

Consider exporting logs before deletion for compliance purposes.


Announcements

Location: /admin/announcements

Announcements are short, admin-authored notices shown on the login/register pages and above the calendar. Unlike most content in BetterShift, a title and body are written once and shown as-is to every viewer — they are not translated per locale.

Managing Announcements

Creating, editing and deleting announcements requires the same permission as system settings: admin or superadmin (canManageSystemSettings). There is no separate role tier for this section.

Placement

Each announcement targets one or both of:

  • Auth pages — shown on the login and registration pages, for logged-out visitors
  • Dashboard — shown above the calendar, for signed-in users

At least one placement must be selected; an announcement with neither is rejected as a mistake rather than saved.

Tone

Three tones control the banner's icon and color: Info, Warning, and Danger.

Enabled Flag and Scheduling Window

  • The Enabled toggle takes an announcement out of rotation without deleting it.
  • An optional start and end date can further restrict visibility to a date range; either side may be left blank, and when both are set the end must be after the start.
  • The table shows each announcement's combined status: Active, Scheduled (before its start date), Expired (past its end date), or Off (disabled).

Dismissal

Dismissing an announcement's banner (the × button) is stored per browser in localStorage, not on the server, as one shared list of dismissed ids covering both the auth and dashboard placements — dismissing on one surface hides that announcement on the other too. There is no admin-side way to see who dismissed an announcement or to reset dismissals centrally — a browser that already dismissed an announcement keeps it hidden even if the announcement is later edited, disabled and re-enabled, or temporarily outside its window, until local storage is cleared or the dismissed list (capped at the 100 most recent ids) evicts that id.


Rate Limiting

Admin operations are rate-limited to prevent abuse:

# User mutations (ban/unban/delete/edit): 10 per minute
RATE_LIMIT_ADMIN_USER_MUTATIONS=10
RATE_LIMIT_ADMIN_USER_MUTATIONS_WINDOW=60

# Password resets: 5 per 5 minutes
RATE_LIMIT_ADMIN_PASSWORD_RESET=5
RATE_LIMIT_ADMIN_PASSWORD_RESET_WINDOW=300

# Bulk operations: 3 per 5 minutes
RATE_LIMIT_ADMIN_BULK_OPERATIONS=3
RATE_LIMIT_ADMIN_BULK_OPERATIONS_WINDOW=300

# Calendar mutations: 10 per minute
RATE_LIMIT_ADMIN_CALENDAR_MUTATIONS=10
RATE_LIMIT_ADMIN_CALENDAR_MUTATIONS_WINDOW=60

# Announcement create/update/delete: 20 per minute
RATE_LIMIT_ADMIN_ANNOUNCEMENT_MUTATIONS=20
RATE_LIMIT_ADMIN_ANNOUNCEMENT_MUTATIONS_WINDOW=60

Security Considerations

  1. Audit everything: All admin actions are logged with IP and user agent
  2. Principle of least privilege: Only grant admin roles when necessary
  3. Regular review: Periodically review admin users and audit logs
  4. Protect superadmin: The superadmin account should use a strong, unique password
  5. Session security: Admin sessions follow the same security as regular sessions