> ## Documentation Index
> Fetch the complete documentation index at: https://docs.augustin.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Adding people

Every person exists once, in Pocket-ID (`https://pocket-id.augustin.ai`). Apps
sign people in with Pocket-ID and create their profile the first time they log
in. Two groups decide what a person can reach:

* `guest`: the shared apps below, as a normal user.
* `admins`: everything, as an admin, including the apps behind the shared Envoy
  gate (which only lets `admins` through).

## Add a person

1. Pocket-ID → **Administration → Users → Add user**. Username is lowercase and
   becomes their username in every app (Jellyfin, Seerr, BookOrbit, RomM).
   Email is required. Leave **Admin** off.
2. **Groups**: tick `guest` (or `admins`).
3. User row → **⋯ → Login code** → pick an expiry (one day is fine) → copy the
   link (`https://pocket-id.augustin.ai/lc/<code>`) and send it to them. Opening
   it signs them in once; Pocket-ID then asks them to add a passkey. After that
   they sign in with the passkey everywhere.

If the person already has a Jellyfin account (Ella, Erin, Jim), give them the
**same username** in Pocket-ID. Their first SSO login attaches to the existing
Jellyfin user, so watch history and favourites stay.

## What they get

| App | Login | New `guest` user | New `admins` user | Manual step left |
| - | - | - | - | - |
| Jellyfin (`jellyfin.augustin.ai`) | **Sign in with Pocket-ID** button (SSO plugin), local password still works | Account created on first login, normal user, no delete | Account created, Jellyfin admin | None |
| Jellyfin TV / phone apps (Swiftfin, Jellyfin tvOS, Streamyfin) | Quick Connect: the app shows a code, they enter it in Jellyfin web → Profile → Quick Connect | Works once they have logged in on the web once | same | Log into the web once first |
| Seerr (`seerr.augustin.ai`) | **Use Quick Connect** (Jellyfin login) | Seerr user created on first login, default request permissions | Created, then make admin in Seerr → Users | Admins only: grant Seerr admin |
| BookOrbit (`bookorbit.augustin.ai`) | Native Pocket-ID OIDC | Created on first login (download, OPDS, Kobo, KOReader sync) | Created, `manage_app_settings` | None |
| RomM (`romm.augustin.ai`) | Native Pocket-ID OIDC | Created on first login | Created, RomM admin | None |
| Shelfmark (`shelfmark.augustin.ai`) | Native Pocket-ID OIDC, sends you straight to Pocket-ID | Created on first login, normal user; requests download straight away and land in BookOrbit | Created, Shelfmark admin | None |
| Outline (`outline.augustin.ai`) | Native Pocket-ID OIDC (client not group-restricted) | Created on first login | Created | Make admin in Outline settings if wanted |
| Vaultwarden (`vaultwarden.augustin.ai`) | Envoy gate (admins) + Pocket-ID SSO | Not reachable (gate is admins-only) | Needs an invite from `/admin`, then SSO + master password | Invite |
| Home Assistant | Local HA users only (HA has no OIDC) | No | No | Create the user in HA → Settings → People |
| ntfy | Local ntfy users | No | No | `ntfy user add` + `ntfy access` |
| Stalwart mail / Bulwark | Local Stalwart accounts | No | No | Create the account in Stalwart admin |
| Grafana, Sure, Miniflux, Yamtrack, Beszel, \*arr apps, qBittorrent, Temporal, Bifrost, SearXNG, Nextflux, Excalideck, webapps | Envoy gate and/or OIDC client limited to `admins` | No | Grafana creates the user; the rest are single-user, Augustin only | n/a |

## Jellyfin SSO setup (lives in Jellyfin's config PVC, not git)

* Plugin: **SSO Authentication** from the maintained fork's repository
  `https://raw.githubusercontent.com/k0lin/jellyfin-plugin-sso/manifest-release/manifest.json`
  (Dashboard → Plugins → Repositories). Version 5.0.x is the line for Jellyfin
  10.11; 5.1+ needs Jellyfin 12. The original 9p4 repository is archived.
* Provider name `pocketid`, Pocket-ID client id `jellyfin` (callback
  `https://jellyfin.augustin.ai/sso/OID/redirect/pocketid`, PKCE, groups
  `admins` + `guest`), role claim `groups`, roles `admins`,`guest`, admin
  role `admins`, username claim `preferred_username`, scheme override `https`.
* The login button is the branding "Login disclaimer" (Dashboard → General →
  Branding), a form posting to `/sso/OID/start/pocketid`.
* The plugin writes its config, client secret and user links to
  `/config/data/plugins/configurations/SSO-Auth.xml` at runtime, so it is not
  managed from git; the PVC backup covers it. Rotate the secret by adding a new
  one on the Pocket-ID client and re-saving the plugin settings.
* Break-glass: `augustin` keeps a local Jellyfin password (in the vault under
  `jellyfin.augustin.ai` / `augustin`). There is no separate `admin` user.

## Asking the assistant to add someone

The Pocket-ID admin API (`STATIC_API_KEY` in the `pocket-id` secret, header
`X-API-Key`) covers the whole flow:

* `POST /api/users` with `username`, `email`, names and `userGroupIds`
  creates the user in the right group.
* `POST /api/users/<id>/one-time-access-token` with `{"ttl": <seconds>}`
  returns a token; the setup link is `https://pocket-id.augustin.ai/lc/<token>`.
* `POST /api/users/<id>/one-time-access-email` emails the link instead (needs
  SMTP configured in Pocket-ID).

Give the assistant the name, username, email and group.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.