Repository navigation
Document the minimal API key permissions for each feature #316
Description
What and why
Document the minimal API-key permissions for each NOVA feature, on the website and in the Add server sheet, so users can create a least-privilege key instead of an ADMIN key.
User demand: a user objected to apps that want broad key permissions (r/unRAID, 20 points, 2026-04-18): https://www.reddit.com/r/unRAID/comments/1soktaq/ . The Unraid documentation recommends it: "Use specific permissions instead of ADMIN role when possible" (https://docs.unraid.net/API/programmatic-api-key-management/).
Other apps: Unraid Deck offers a preset key template that includes API_KEY:CREATE_ANY (reported second-hand, medium confidence; https://ca.unraid.net/apps/unraid-deck-0pm0cs30j7fmhz). NOVA can state the opposite as a documented promise.
What NOVA has today
README.md only says to generate an API key. The Add server sheet is ui/screens/server/AddEditServerSheet.kt.
API side
Roles per the Unraid docs: ADMIN ("full system access"), CONNECT, VIEWER ("read-only access"), GUEST. Resources and actions per feature (for example docker:read, vm:*) must be derived from the operations in queries.graphql, mutations.graphql and subscriptions.graphql and tested; this list is not yet verified against a server.
Constraints from NOVA's principles
Least-privilege keys; official API only. The docs must not suggest a key that can manage API keys.
Open questions
- Which exact permission set does each feature need (read-only monitoring, Docker control, VM control, array and parity control, notifications)?
- Can the Add server sheet link to the Unraid page that creates a key with a prefilled scope (see the separate "Sign in with Unraid" issue)?
Acceptance criteria
- A table "feature -> required permissions" in the README and on the website, verified with a key limited to those permissions.
- The Add server sheet links to it.
- No documented setup asks for ADMIN or key-management permissions.
Size
S
Activity
nofuturekid commentedon Nov 13, 2026
Live check of the permission table (Unraid 7.4.0, API 4.37.11, temporary key, deleted afterwards), documented in #339:
DOCKER:UPDATE_ANY(refused without it, accepted with it). Effective rights are the role's plus the explicit permissions.VMS:UPDATE_ANY,NOTIFICATIONS:UPDATE_ANY,NOTIFICATIONS:DELETE_ANY; that these are sufficient is from the source.Correction: a key without a role cannot be created with the server's command line tool, so the recipe is VIEWER plus explicit permissions. The Add server sheet link is still open.
feat: detect the API version of the server and what the API key may do