Authentication

Better Reports supports optional HTTP Basic Authentication with multiple credential sources.

Login Page

The UI has a dedicated login page at /login. When you access the app without valid credentials, you'''ll be redirected there.

# Login via API
curl -X POST http://localhost:3000/api/login \
  -H "Content-Type: application/json" \
  -d '\''{"user": "admin", "password": "password123"}'\''

Credential Resolution

The server resolves credentials in this priority order:

1. Environment Variables

Set both REPORTS_USER and REPORTS_PASS in your environment:

REPORTS_USER=admin
REPORTS_PASS=your-secure-password

2. Credentials File

If env vars are not set, the server looks for .credentials.json in the app root. This file is created automatically when you change the password via the UI or API:

curl -X POST http://localhost:3000/api/change-password \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic $(echo -n '\''admin:password123'\'' | base64)" \
  -d '\''{"currentPassword": "password123", "newPassword": "my-new-password"}'\''

3. Default Credentials

If neither env vars nor credentials file exist, the server uses the default hardcoded credentials:

• User: admin
• Password: password123

WARNING

The default credentials are insecure. Always set custom credentials in production.

How Authentication Works

1. The UI sends credentials with every request via the Authorization: Basic header
2. On 401 responses, the UI redirects to /login
3. Credentials are stored in sessionStorage (cleared when the tab is closed)
4. The login page posts to /api/login to validate credentials
5. A logout button appears in the header navigation

API Authentication

All protected API endpoints require the Authorization header:

curl http://localhost:3000/api/templates \
  -u "admin:your-secure-password"

Security Considerations

• Use a strong, unique password
• Always use HTTPS in production (see Docker for automatic TLS)
• The app does not support multiple users; it'''s designed for single-user or team-shared authentication
• Credentials are transmitted in cleartext with Basic Auth; HTTPS is mandatory in production
• Default credentials admin/password123 are hardcoded � change them immediately
• The .credentials.json file stores the password in plaintext on disk