Authentication

homescreen-hero supports multiple authentication methods to protect your dashboard. You can use password-based login, Plex OAuth (sign in with your Plex account), or both.

Auth Methods

Method	Description
Password	Simple username/password login. Good for single-admin setups.
Plex	Sign in with your Plex account. Users must have access to the same Plex server.
Both	Allows either password or Plex login. Useful when you want admin access via password and user access via Plex.

Setup

Password Authentication

1. Set your credentials in .env:

HSH_AUTH_PASSWORD=your-secure-password
HSH_AUTH_SECRET_KEY=any-random-string-for-jwt-signing

2. Enable auth in config.yaml (or via the Settings page):

auth:
  enabled: true
  method: password
  username: admin

The admin username defaults to admin but can be changed in the config.

Plex Authentication

1. Set only the secret key in .env:

HSH_AUTH_SECRET_KEY=any-random-string-for-jwt-signing

2. Enable Plex auth in config.yaml:

auth:
  enabled: true
  method: plex
  auto_approve_users: true

When a user signs in via Plex OAuth, homescreen-hero verifies they have access to the configured Plex server. The server owner is automatically granted the admin role.

Both Methods

auth:
  enabled: true
  method: both
  username: admin
  auto_approve_users: true

This shows both login options on the login page. Password login always creates an admin session. Plex login assigns roles based on server ownership.

Roles

Role	Permissions
Admin	Full access to all settings, integrations, rotation, tools, and user management
User	Limited access. User-specific features are currently in development. Non-admin users see a landing page with a logout option.

The Plex server owner is always an admin. Other Plex users default to the user role but can be promoted by an admin.

User Management

Admins can manage users from Settings > Users:

• Approve/deny pending users (when auto_approve_users is false)
• Change roles between admin and user
• Delete user accounts

You cannot modify or delete your own account.

Auto-Approve

When auto_approve_users is true (the default), any Plex user with access to your server can sign in and immediately use the dashboard. Set it to false if you want to manually approve each new user before they get access.

Token Expiration

JWT tokens expire after 30 days by default. You can change this in the config:

auth:
  token_expire_days: 7

Configuration Reference

auth:
  enabled: true              # Enable/disable authentication
  method: password           # "password", "plex", or "both"
  username: admin            # Username for password login
  token_expire_days: 30      # JWT token lifetime in days
  auto_approve_users: true   # Auto-approve new Plex users

Sensitive values (password and secret_key) should be set via environment variables rather than in the config file.