Users & API Keys View

Relevant source files

The following files were used as context for generating this wiki page:

• dashboard/views/users/index.ts
• src/web/store/session/user-store.ts
• dashboard/views/shell/index.ts
• README_EN.md
• dashboard/AGENTS.md

The Users & API Keys View provides the administrative interface for managing control-plane accounts and their associated credentials. It allows administrators to create, delete, and configure users who access the proxy via OpenAI-compatible API keys.

This module separates proxy users from upstream Freebuff accounts. Users consume the proxy's aggregated resources using unique API keys starting with the sk-fb- prefix. The interface is restricted to users with the admin role and serves as the primary gateway for user lifecycle management.

Sources: README_EN.md:104-106, src/web/store/session/user-store.ts:40

Architecture and Data Persistence

The system uses a JSON-file backend for user data, stored at /data/users.json. The UserStore class manages all CRUD operations and persists changes to this file. To ensure security, the system stores salted password hashes rather than plain text and never transmits sensitive fields like salt or passwordHash to the frontend.

User Data Model

The following table describes the fields within a user record:

Field	Type	Description
username	string	Unique identifier for the user (2-64 characters).
salt	string	Random hex string for password hashing.
passwordHash	string	Result of scrypt hashing the password with the salt.
role	admin | user	Permission level; admins can access management views.
apiKey	string	The OpenAI-compatible key for API requests.
createdAt	string	ISO timestamp of account creation.
lastSeenAt	string | null	ISO timestamp of the last successful login.

Sources: src/web/store/session/user-store.ts:24-46

Data Flow Diagram

This diagram shows how the UserStore interacts with the file system and provides filtered data to the frontend view.

The diagram represents the lifecycle of user data from disk to UI. Sources: src/web/store/session/user-store.ts:98-112

Administrative Interface

The Users View is a dedicated panel within the dashboard, accessible only to administrators via the sidebar navigation. It employs a standard Single Page Application (SPA) routing mechanism to preserve UI state when switching between tabs.

View Components

The interface consists of three primary elements:

1. User Table: Displays the username, role, and a masked version of the API key.
2. User Actions: Provides buttons for resetting keys, changing passwords, and deleting accounts.
3. New User Form: Allows administrators to define a new username, initial password, and role.

Sources: dashboard/views/users/index.ts:184-256

User Creation Sequence

When an administrator creates a new user, the following sequence occurs:

The sequence shows the validation and generation steps during user creation. Sources: src/web/store/session/user-store.ts:153-181, dashboard/views/users/index.ts:242-255

API Key Management

API keys are the primary credentials for downstream agents. The proxy identifies users by the Authorization: Bearer <key> header in incoming requests.

Key Lifecycle Operations

• Generation: The system generates keys using 24 random bytes converted to hex, prefixed with sk-fb-.
• Masking: To prevent accidental exposure in the UI, keys are masked to show only the first 12 and last 4 characters (e.g., sk-fb-abcdef…1234).
• Resetting: Administrators can reset a user's key at any time. This invalidates the old key immediately and generates a new one.
• Copying: The UI provides a one-click copy button to retrieve the full API key from the backend.

Sources: src/web/store/session/user-store.ts:40, dashboard/views/users/index.ts:211-218

API Endpoints

The dashboard communicates with the backend via a set of dedicated management endpoints.

Method	Endpoint	Description
GET	/api/users	Returns a list of all public user records.
POST	/api/users	Creates a new user with specified role and password.
DELETE	/api/users/:username	Removes a user record from the system.
POST	/api/users/:username/password	Updates the password for a specific user.
POST	/api/users/:username/reset-key	Generates a new API key for the user.

Sources: dashboard/views/users/index.ts:192-277, scripts/gates/checks/doc/check-docs.ts:120-135

Security Safeguards

The system implements several safeguards to prevent administrative lockout and data loss:

• Admin Retention: The setRole function prevents deleting or demoting the last administrator.
• Self-Deletion Prevention: The UI disables the delete button for the currently logged-in user.
• Corruption Handling: If users.json is corrupted, the system refuses to start rather than performing a silent reset, which prevents accidental data loss.
• Default Admin: If no users exist, the system bootstraps a default admin based on the ADMIN_PASSWORD environment variable.

Sources: src/web/store/session/user-store.ts:113-118, src/web/store/session/user-store.ts:210-213, dashboard/views/users/index.ts:223-228

Conclusion

The Users & API Keys View centralizes control over proxy access. By isolating proxy authentication from upstream Freebuff accounts, it enables multi-user resource sharing and provides granular security controls for administrators. The combination of persistent JSON storage and salted hashing ensures that user credentials remain secure and manageable throughout the project's operation.