magnus919_agent-skills/jellyfin/references/user-scoping-and-errors.md

Jellyfin user scoping — the userId matrix

The single most common Jellyfin integration failure after authentication: a request that authenticates fine but 404s or 400s because which user the query is about was never stated. Jellyfin's data model is per-user at the library level; most read endpoints need you to say whose library you are looking at.

Why user id is everywhere

A Jellyfin library is not one global catalog. Views, playstate, favorites, resume points, and parental-control visibility all attach to a user. The authentication layer may or may not imply a user:

• User access token (from AuthenticateByName): implies one user. Recent servers fall back to that user when userId is omitted on some endpoints.
• API key (from Dashboard → API Keys): implies NO user. AuthorizationInfo.User stays null and the request gets administrator role. Every user-scoped concept must be named explicitly with a userId parameter — including /UserViews, which is meaningless without one.

The bundled CLI always sends userId explicitly on user-scoped commands regardless of which credential type it holds. That is the cross-version-safe baseline.

The userId requirement matrix

Endpoint	User token, userId omitted	API key
GET /Items	400 — body userId is required (servers enforce if (!isApiKey && user is null) return BadRequest("userId is required"))	Optional — omitted means an unrestricted, userless view; pass it anyway for UserData in DTOs
GET /Items/{itemId}	Defaults to the token's user; userId supplies whose UserData embeds	Pass explicitly for user data
GET /UserViews	Parameter accepted; pass it	REQUIRED to be meaningful
GET /Shows/{seriesId}/Seasons / Episodes	≥10.9 falls back to token user; ≤10.8 crashes on omission — always pass	REQUIRED
GET /Shows/NextUp	Same version split as above — always pass	REQUIRED
GET /Items/Latest	userId scopes "recently added for whom"; always pass	REQUIRED for meaningful results
GET /Search/Hints	Optional — "omit to search all"	Optional
GET /Users/Me	Works (returns token's user)	400 Token is not owned by a user.
GET /System/Info, /System/Info/Public, /Users	No user concept	Fine

Note the deliberate trap in /Users/Me: it is the natural "who am I" endpoint for a user token and returns exactly the id you need — but with an API key it is a 400, by design, because an API key is nobody.

400 vs 404: absent vs invalid userId on /Items

Two distinct failure signatures, enforced in this order by the items controller (verified at master and v10.10.7):

1. The user lookup runs first: a supplied-but-nonexistent userId throws ResourceNotFoundException → mapped to 404 (Error processing request. body).
2. Then the guard: an ABSENT userId on non-API-key auth returns 400 with the literal string body userId is required (not the middleware's generic text).

So: 400 userId is required = you forgot the parameter; 404 = the parameter names a user that does not exist. Mock both distinctly.

Finding a user id without logging in as one

1. GET /Users (any valid token): array of UserDto with Name and Id. The administrator-flavored listing — API keys see everyone.
2. GET /Users/Public (no auth): only users flagged visible on login screens.
3. After AuthenticateByName: the response's User.Id is the documented primary.
4. With a user token: GET /Users/Me.

# Discover user ids with an API key
curl -s -H 'Authorization: MediaBrowser Token="YOUR_API_KEY"' \
  "http://localhost:8096/Users" | jq -r '.[] | [.Name, .Id] | @tsv'
# → alice    6eec632a-ff0d-4d09-aad0-bf9e90b14bc6

Scoping errors look like 404s

The confusion this reference exists for: GET /Items (or /Shows/NextUp) called without a userId under a context where one is required does not answer "you forgot the user" on every endpoint and version — older servers crash (NextUp ≤10.8: 500 from an empty-Guid ArgumentException), and user-token fallbacks silently change results. Symptoms cluster as "endpoint exists but returns 400/404/empty" even though the token is perfectly valid. The fix is uniform: resolve the user id once, pass it explicitly on every user-scoped call.

The bundled CLI mirrors that baseline: recent, next-up, and item require JELLYFIN_USER_ID or --user-id before any network call, refuse to guess an administrator, and dry-run previews show the userId that would have been sent.

Sources

• https://api.jellyfin.org/ — official Jellyfin API reference (ReDoc), version 12.0.0 stable
• https://api.jellyfin.org/openapi/jellyfin-openapi-stable.json — canonical OpenAPI spec (/Users/Me 400 "Token is not owned by a user.", userId parameter descriptions across /Items, /Items/Latest, /Shows/*, /Search/Hints)
• https://github.com/jellyfin/jellyfin — server source: ItemsController.cs (userId-required guard and 400/404 ordering), RequestHelpers.cs (GetUserId token fallback), TvShowsController.cs (NextUp userId version history), AuthorizationContext.cs (API key ⇒ User null + admin role)
• https://mintlify.wiki/jellyfin/jellyfin/api/authentication/overview — official server docs (API key vs user token semantics)
• https://gist.github.com/nielsvanvelzen/ea047d9028f676185832e51ffaf12a6f — core-developer authorization guide (API-key identity behavior)