Skip to main content
Battles Record includes a user system for managing access to the dashboard.

​
User Roles

RolePermissions
AdminFull access: channels, recordings, settings, users
ViewerView-only: recordings library, active recordings

​
Admin Permissions

  • Add, edit, and delete channels
  • Start, stop, and delete recordings
  • Configure all settings
  • Manage users
  • Access API with full permissions

​
Viewer Permissions

  • Browse recording library
  • View active recordings
  • Stream/download recordings
  • View (not change) channel list

​
First-Time Setup

On first launch, create an admin account:
1

Open Dashboard

Navigate to http://localhost:8080
2

Create Admin

Enter username and password for the admin account
3

Login

Use your new credentials to access the dashboard
Store your admin password securely. If forgotten, you’ll need to reset via the command line or config file.

​
Managing Users

​
Add User

1

Go to Settings

Navigate to Settings → Users
2

Click Add User

Enter username, password, and role
3

Save

The new user can now log in

​
Edit User

1

Go to Settings

Navigate to Settings → Users
2

Select User

Click on the user to edit
3

Modify

Change password, role, or disable account

​
Delete User

1

Go to Settings

Navigate to Settings → Users
2

Select User

Click on the user to delete
3

Delete

Click Delete User and confirm
You cannot delete the last admin account.

​
View & Revoke Sessions

Admins can manage active sessions for any user:
1

Go to Users

Navigate to Settings → Users and select a user
2

View Sessions

See all active sessions with login time and last activity
3

Revoke

Revoke a specific session or all sessions for the user

​
Authentication

​
Session Management

SettingDescriptionDefault
Session DurationToken validity period24 hours (86400 seconds)
Refresh Grace PeriodTime after expiry where refresh is still allowed1 hour (3600 seconds)
Max SessionsConcurrent logins per userUnlimited

​
Token Refresh Flow

Battles Record uses proactive token refresh to maintain sessions seamlessly:
  1. Proactive refresh - The client automatically refreshes tokens 5 minutes before they expire
  2. Request retry - If a request fails with TOKEN_EXPIRED, the client attempts a refresh and retries
  3. Grace period - Expired tokens can still be refreshed for up to 1 hour after expiry
  4. Session expired - If refresh fails (beyond the grace period), the user sees a session expired modal and must re-authenticate
Under normal usage, token refresh happens transparently in the background. Users only need to re-authenticate if they’ve been inactive for longer than the grace period.

​
Password Requirements

Configure password policy in Settings → Security:
SettingDescriptionDefault
Min LengthMinimum characters8
Require UppercaseAt least one A-ZNo
Require NumberAt least one 0-9No
Require SymbolAt least one special charNo

​
Two-Factor Authentication

2FA is optional and can be enabled per-user.
1

Go to Profile

Click your username → Profile
2

Enable 2FA

Click Enable Two-Factor Authentication
3

Scan QR Code

Use an authenticator app (Google Authenticator, Authy, etc.)
4

Verify

Enter the code to confirm setup

​
Access Control

​
IP Allowlist

Restrict dashboard access to specific IPs:
1

Go to Settings

Navigate to Settings → Security → IP Allowlist
2

Add IPs

Enter allowed IP addresses or CIDR ranges
3

Enable

Toggle on to enforce the allowlist
Be careful not to lock yourself out. Ensure your current IP is in the allowlist before enabling.

​
Reverse Proxy

When behind a reverse proxy:
  1. Configure proxy to pass X-Forwarded-For header
  2. In Settings → Security, enable Trust Proxy Headers
  3. Add proxy IP to trusted proxies list

​
API Authentication

​
API Keys

Create API keys for programmatic access:
1

Go to Settings

Navigate to Settings → API → API Keys
2

Create Key

Click Create API Key and enter a label
3

Set Permissions

Choose read-only or full access
4

Copy Key

Copy the key immediately - it won’t be shown again
Use in requests: 
curl -H "Authorization: Bearer YOUR_API_KEY" \
  http://localhost:8080/api/channels

​
JWT Tokens

Login to receive a JWT token: 
curl -X POST http://localhost:8080/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "yourpassword"}'
Response: 
{
	"token": "eyJhbGciOiJIUzI1NiIs...",
	"expires_at": "2026-02-03T14:30:00Z"
}
Use in subsequent requests: 
curl -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  http://localhost:8080/api/channels

​
Password Reset

​
As Admin

Reset another user’s password:
1

Go to Settings

Navigate to Settings → Users
2

Select User

Click on the user
3

Reset Password

Click Reset Password and enter new password

​
Self-Service

If enabled, users can reset their own password:
1

Go to Login

Click Forgot Password on login page
2

Enter Username

Enter your username
3

Check Email

If email notifications are configured, receive reset link

​
CLI Reset

If locked out, reset via command line: Desktop: 
battles-record --reset-password admin
Docker: 
docker exec -it battles-record /app/battles-record --reset-password admin

​
Session Security

SettingDescription
Secure CookiesRequire HTTPS for auth cookies
Same-SiteCookie same-site policy
HTTP OnlyPrevent JavaScript cookie access
Enable Secure Cookies when using HTTPS (required for production).

​
Local-Only Mode

When running as a desktop app sidecar, the daemon operates in local-only mode:
SettingBehavior
AuthenticationNo login required
PermissionsAll requests treated as Admin
AccessOnly accessible from localhost
ShutdownPOST /api/shutdown endpoint available for graceful daemon shutdown
Local-only mode is automatically enabled when the desktop app manages the daemon as a sidecar process. It is not available in Docker or standalone daemon deployments.