Accounts and Access

Every person on a Plinthio server has their own account, with their own progress, bookmarks, ratings and look. There's no self sign-up: the admin made in the setup wizard adds everyone else in Admin → Users.

Roles

Roles are enforced by the server on every request, not just hidden in the app.

	Viewer	Editor	Admin
Read, watch and listen; progress, bookmarks, ratings, lists, custom folders	Yes	Yes	Yes
Request titles; join watch parties (and start one, when parties are on)	Yes	Yes	Yes
Hide titles from their own shelves	Yes	Yes	Yes
API keys and reading apps for themselves	Yes	Yes	Yes
Edit metadata, upload covers, series settings (name, reading direction, age rating)		Yes	Yes
Add series and titles to Kids Mode		Yes	Yes
Review the request queue		Yes	Yes
Set intro and credits markers (API)		Yes	Yes
The Admin panel: libraries, health, users, logs, activity, server settings, backups			Yes
Hide a title from everyone (API)			Yes

Usernames are 1–64 characters: letters and numbers from any language, spaces, and . _ @ -. They must start with a letter or number. Passwords are at least 8 characters.

Managing Accounts

In Admin → Users, each person is a row showing their role and badges for expiry, two-factor, home only, Kids and content limit. The last sign-in says whether it came from away from home.

• Add a user: username, password, role, and access with No end date or Until a date….
• Edit (tap a row): rename, change role, set access (+1 day, +1 week or +1 month from the current end, no end date, or a new date), Can use Plinthio away from home, Kids account, content limit, reset two-factor, and set a new password. Setting a new password signs the person out everywhere.
• Delete (in Edit): removes the account with its progress, ratings, lists and API keys.

Content Limits

Give an account a content limit in Admin → Users → Edit: No limit, Everyone only, Up to Teen or Up to Mature. You also choose whether the account sees titles that haven't been rated. Off is strict: only rated titles at or under the limit.

• A title's rating is its own if it has one, otherwise its series' rating (set in the series settings, or read from ComicInfo.xml's AgeRating).
• The limit applies everywhere: shelves, search, Continue, lists, direct links, file and page links, watch parties, OPDS, Mihon and KOReader.
• Admin → Health lists titles with no rating, which matters when accounts hide unrated titles.

Kids Mode

A kids account sees only what an admin or editor has made kids-safe. Everything else disappears, as if it weren't on the server.

1. Make titles kids-safe:
   • a whole library: switch it on in Admin → Kids Mode → Whole libraries, or
   • a series or single title: press Kids on its page (editors and admins). A series is added whole, including volumes or episodes added later.
2. In Admin → Users, edit the child's account and turn on Kids account.

Admin → Kids Mode also lists the series and titles added one by one, with a remove button.

• Admin accounts can't be kids accounts, and you can't make your own account one.
• A content limit still applies on top. A Teen-rated series in Kids Mode stays hidden from a kids account limited to Everyone.
• Kids Mode applies everywhere, including direct links, files, watch parties and the reading apps.

Hiding Titles

• Anyone can hide a title from their own shelves with Hide from Shelf in its card menu, and bring it back in Settings → Hidden titles.
• An admin can hide a title from everyone through the API. There's no button for this.

A hidden title is also refused when opened by a direct link.

Expiring Accounts

For a guest, set an end date when creating the account, or later in Edit. An expired account can't sign in or use its API keys (P103) until an admin extends it.

Signing In and Sessions

• A sign-in lasts 7 days and is renewed each time the app opens, so regular use never signs you out, while a token on a lost device stops working within a week.
• Changing your password, or Settings → Security → Sign out of all devices, ends every session at once.
• Failed sign-ins are limited to 10 per 15 minutes per address. Successful sign-ins don't count, so a household behind one address never locks itself out.
• Image, audio and video links carry a separate media token. It's valid for 24 hours, only opens media, and is never your sign-in token, so a copied media link can't be used to control your account.
• Admin → Activity shows each person's sign-in history and what they've been reading and watching.

Two-Factor Sign-In

Optional, for anyone. With it on, signing in asks for a 6-digit code from an authenticator app after your password. Any app that supports TOTP works, such as Google Authenticator, Microsoft Authenticator, 1Password, Bitwarden or Aegis.

Turning It On

1. Open Settings → Security and press Turn on two-factor. It's also offered at the end of onboarding and of the setup wizard.
2. Scan the QR code with your authenticator app, or copy the key into it.
3. Type the 6-digit code the app shows.
4. Save your ten backup codes. Each one signs you in once instead of a code, if you lose your phone. They're only shown once. Press I've saved these codes when you're done.

Using It

• Sign in with your username and password, then enter the code. "Lost your phone?" switches to a backup code.
• Each code works once, and a phone clock that's slightly off still works.
• Make new backup codes, or turn two-factor off, from Settings → Security. Both need your password and a current code (or a backup code). API keys can't change two-factor.
• Locked out? An admin can reset it in Admin → Users → Edit → Reset. That signs the account out everywhere. Its owner then signs in with just the password and can set two-factor up again.
• The secret is stored encrypted with a key derived from the server's sign-in secret (/config/jwt.secret). If that file is deleted or changed, everyone has to set two-factor up again.
• Admins can require two-factor for sign-ins from outside the home network. It's never required at home.

Away From Home

Whether each account can be used outside your home network is covered in Away From Home.

• Admin → Network → Allow access from outside the home network is the server-wide switch.
• Admin → Users → Edit → Can use Plinthio away from home is the per-account switch (on by default). Off, the account only works at home and over Tailscale, including its sessions, reading apps and API keys. Admins can't switch it off for themselves while away.
• Admin → Network → Require two-factor away from home: accounts without two-factor can then only sign in at home, where they can set it up.

API Keys

Each person makes their own keys in Settings → Apps & API keys. A key acts as its owner, with their role and limits.

• A key is shown once, when made. The server stores only a SHA-256 hash, plus an MD5 hash used by KOReader, so a leaked database can't be turned back into working keys.
• Apps use a key as X-API-Key: <key>, or as the password with your username. Reading apps sign in this way, so no app ever holds your real password.
• Make one key per app. Revoking a key signs that app out.
• Keys made before 1.0.0 don't work for KOReader. Make a new one.

See Reading Apps and API.