Users and Permissions
GamesDownloader is multi-user from the ground up. One person owns the server as an administrator, and everyone else - family, housemates, friends on the local network - gets their own account with a role that controls what they can see and do. Access is enforced with JWT authentication, refined with per-user overrides and per-game restrictions, and can be delegated to an external identity provider through Single Sign-On.
This page covers the role model, permission overrides, per-game and per-library access control, session handling, self-service password reset, SSO, and registration modes.
- Roles
- Per-user permission overrides
- Per-game access control
- Authentication and sessions
- Forgot Password (self-service reset)
- Single Sign-On (SSO)
- Registration modes
- Library visibility and access (Settings → Libraries)
Settings → Users: user management, invite codes, and active sessions
Every account has one of four roles. Roles are a hierarchy of trust: each higher role is meant to add capabilities on top of the plain User baseline.
| Role | Intended capabilities |
|---|---|
| Admin | Full control of the server - users, roles, sessions, libraries, access rules, metadata scraping, security settings, and everything the lower roles can do. |
| Uploader | Everything a User can do, plus adding game files to the library (uploads). |
| Editor | Everything a User can do, plus editing game metadata and artwork. |
| User | Browse the library, download games, play ROMs in the browser, manage their own save states and battery saves, and file game requests. |
A capability view of the same model:
| Capability | User | Editor | Uploader | Admin |
|---|---|---|---|---|
| Browse library, download games, play ROMs | + | + | + | + |
| Manage own save states / battery saves | + | + | + | + |
| Submit game requests and vote | + | + | + | + |
| Connect a personal GOG account (in Profile) | + | + | + | + |
| Edit game metadata and artwork | + | + | ||
| Upload game files | + | + | ||
| Add games via torrent (magnet / .torrent) | + | |||
| Clear metadata (per-ROM or per-platform) | + | |||
| Manage users, roles, and sessions | + | |||
| Manage libraries and access rules | + | |||
| Server, network, and security settings | + |
Some actions are strictly admin-only regardless of any other setting, for example clearing metadata and adding games via torrent.
The exact set of actions each account can perform can be fine-tuned beyond its base role using per-user overrides (below), so the table above describes the default intent of each role rather than a fixed, immovable boundary.
On top of the base role, an administrator can apply per-user permission overrides to grant or restrict individual capabilities for a specific account. Use this when a single person needs something their role does not normally include, without promoting them to a broader role for everyone-else's-worth of extra power.
Related per-user knobs live elsewhere in Settings too - for example per-user download speed limits are configured alongside the global cap in Settings → Downloads.
Beyond roles, individual titles can be locked down: per-game access control lets an administrator restrict specific games so they are only visible and downloadable to selected users. This is useful for keeping certain titles out of a child's view, or scoping a game to just the person who owns it. Games without a restriction remain visible to everyone whose role and library visibility allow it.
For restricting a whole library (for example a personal GOG library or a custom library) to specific users, see Library visibility and access below.
Authentication uses JSON Web Tokens (JWT) with a short-lived access token and a longer-lived refresh token, so users stay logged in without re-entering credentials on every request.
Sessions are fully revocable:
- All active sessions are visible in the admin Users panel.
- An administrator can revoke a single session or perform a global revoke of every session for an account.
- Revocation is instant: it is backed by a Redis JTI (JWT ID) blocklist, with a database fallback if Redis is unavailable, so a revoked token stops working immediately rather than lingering until it expires.
Brute-force protection and the safe extraction of the real client IP behind a proxy are covered on the Network & Security page. The token secret (GD_AUTH_SECRET_KEY) is set in the environment, as described on the Configuration page.
Users who cannot log in can reset their own password without an administrator. The Forgot Password flow emails a reset link containing a signed JWT token that:
- expires after 1 hour, and
- is rate limited to prevent abuse.
For the emailed links to point back at the correct address (rather than an internal container hostname), set the Public base URL so reset links resolve for users on your real domain or LAN IP. This is configured and explained on the Network & Security page. Email delivery itself depends on your SMTP configuration - see Email & Notifications.
GamesDownloader can delegate login to an external identity provider so people sign in with an account they already have.
Supported providers:
- Generic OIDC - any OpenID Connect provider, including Keycloak and Authentik.
- GitHub
- Microsoft
Login mode determines how SSO coexists with built-in accounts:
| Mode | Behaviour |
|---|---|
| alongside | Both local username/password login and SSO are offered on the login screen. |
| replace | SSO only. The local login form is hidden, but remains reachable through an emergency local link so an administrator can still get in if the identity provider is down. |
User matching. SSO does not create accounts on its own. When someone signs in through a provider, GamesDownloader matches them to an existing account by email first, then by username. The account must already exist in the database; if there is no match, the SSO login is rejected. This keeps role assignment and access control in your hands - create the account (and set its role) first, then let the user authenticate through the provider.
Because SSO users must exist beforehand, provisioning is a deliberate, admin-controlled step. Plan to create accounts (or invite them, see below) before pointing people at the SSO login.
How new local accounts come into existence is controlled by the registration mode:
| Mode | Behaviour |
|---|---|
| open | Anyone can register a new account. |
| disabled | Self-registration is turned off; only an administrator creates accounts. |
| invite-only | Registration requires a valid invite code. Codes can be time-limited and given a maximum number of uses. |
Registration mode and invite codes are part of the security surface documented on the Network & Security page.
The library registry is data-driven, so libraries can be created, reordered, hidden, and restricted from Settings → Libraries. This page has an admin-only management area at the top and per-user personalisation sections that everyone sees.
Administrators can:
- Enable or disable any library with the glass toggle.
- Reorder libraries with the up/down arrows (this sets the global default order).
- Edit a library's colour and icon (built-in icon picker or upload your own PNG / JPEG / WebP). Custom libraries can also be renamed.
- Create a new library. A plain library can optionally get its own scan folder for game files; alternatively you can create a collections container (which holds collections of games and has no scan folder). See Collections for how collections work.
- Delete custom libraries (built-in libraries cannot be deleted).
Changing which libraries exist and how they are organised affects everyone on the server, so the management area is restricted to administrators.
For eligible libraries an administrator can set an access rule in the inline editor:
- Everyone (public) - visible to all users (subject to their role and per-game restrictions).
- Restricted - visible only to the specific users you tick in the list.
Only certain library kinds can be restricted this way: GOG, custom games, and custom user libraries. Administrators always retain access to every library (their checkbox is forced on and cannot be unticked), so an admin can never lock themselves out.
The lower sections of Settings → Libraries are per-user preferences and are shown to every account:
- Library visibility - each user can toggle which enabled libraries appear in their own navigation, and reorder them for their personal layout.
- Recently added - on themes that have a home feed (that is, non-Classic layouts), choose which libraries contribute to the "recently added" row.
- Home sections - if the active theme registered extra home sections, toggle them on or off.
These choices are personal and do not change what other users see; the administrator's enable/disable and access rules always take precedence over an individual's visibility toggles.
Next: Network & Security and Security