Your favorite shift management application!
Admin Panel Guide
This guide covers the admin panel features in BetterShift, including user management, calendar administration, and audit logging.
Table of Contents
- Overview
- Dashboard
- Roles and Permissions
- User Management
- Calendar Management
- Audit Logs
- Announcements
- 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
- Login with an admin account
- Click your profile menu in the header
- 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:
- Click the action menu and select "Ban User"
- Enter a ban reason (required)
- Optionally set an expiration date
- 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:
- Click the action menu and select "Transfer"
- Search for the new owner by name or email
- Select the user from results
- 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:
- Click "Delete Old Logs"
- Select the cutoff date
- Review what will be deleted
- 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
- Audit everything: All admin actions are logged with IP and user agent
- Principle of least privilege: Only grant admin roles when necessary
- Regular review: Periodically review admin users and audit logs
- Protect superadmin: The superadmin account should use a strong, unique password
- Session security: Admin sessions follow the same security as regular sessions