Users & Settings

Overview

coreX Manager includes a user management system with authentication, two-factor authentication (2FA), theme customization, and global option toggles that control feature availability across the platform.

Authentication

Admin User

On first startup, coreX Manager creates an admin user. The password is read from the ADMIN_PASSWORD environment variable. If unset, a random password is generated and printed to the logs.

Change the default password

If ADMIN_PASSWORD is not set, a random password is generated. Check the startup logs for the password and change it immediately after first login.

Login

  1. Navigate to the coreX Manager URL
  2. Enter username and password
  3. If 2FA is enabled, enter the TOTP code
  4. You receive a JWT token for API access

JWT Tokens

Authentication uses JWT tokens. Tokens are:

  • Issued on login
  • Included in API requests as Authorization: Bearer <token>
  • Refreshable via the refresh endpoint
  • Revocable (individual tokens can be revoked)

Two-Factor Authentication (2FA)

2FA uses TOTP (Time-based One-Time Password) compatible with authenticator apps.

Enabling 2FA

  1. Navigate to Management > Users and open your user profile
  2. Click Enable 2FA
  3. Scan the QR code with your authenticator app
  4. Enter the verification code to confirm
  5. Save the backup codes in a secure location

Disabling 2FA

  1. Open your user profile
  2. Click Disable 2FA
  3. Enter your password to confirm
Backup codes

When you enable 2FA, coreX Manager generates one-time backup codes. Store these securely — each can be used once if you lose access to your authenticator device.

User Management

Creating Users

  1. Navigate to Management > Users
  2. Click Add User
  3. Enter username, email, and password
  4. Assign a role (admin or read-only)
  5. Save

Roles

RoleDescription
adminFull access to all features and settings
read-onlyCan view all pages but cannot make changes

Managing Users

  • Edit user details
  • Reset password
  • Enable/disable 2FA (admin can reset for users who lost access)
  • Delete users (cannot delete the last admin)

Themes

coreX Manager supports runtime theme switching via CSS variables. Users can also create custom themes.

Built-in Themes

6 built-in themes are available:

  • Slate Dark
  • Dracula
  • Tokyo Night
  • Catppuccin Mocha
  • Material Light
  • Catppuccin Latte

Custom Themes

  1. Navigate to Settings > Appearance
  2. Click Create Custom Theme
  3. Clone from a built-in theme or start from scratch
  4. Customize the 18 color variables (backgrounds, borders, text, semantic, status)
  5. Preview live as you edit
  6. Save with a custom name

Theme Persistence

The active theme is persisted to localStorage and applied on page load. Custom themes are also stored in localStorage.

Global Options

Global options control feature availability across the platform. These are the main toggles:

OptionDescription
req_fp_enabledRequest fingerprinting (required for Risk Scoring)
ja4_enabledJA4 TLS fingerprinting
compression_enabledBrotli and zstd compression module
disk_cache_enabledDisk cache (L2) sidecar
resp_transform_enabledResponse transforms (replace, inject, mask)
img_2_webp_enabledImage to WebP conversion
api_armor_enabledAPI Armor (GraphQL, schema validation, profiling)
Feature dependencies

Some features depend on others. For example, Risk Scoring requires req_fp_enabled, and JA4-derived risk fields require ja4_enabled. coreX Manager shows these dependencies in the UI and warns if you try to enable a feature without its prerequisites.

Step-by-Step: Change the Admin Password

  1. Log in as admin
  2. Navigate to Management > Users and open the admin user
  3. Click Change Password
  4. Enter the current password and new password
  5. Save

Step-by-Step: Create a Read-Only User

  1. Navigate to Management > Users
  2. Click Add User
  3. Username: viewer
  4. Email: viewer@example.com
  5. Password: a strong password
  6. Role: read-only
  7. Save

The user can now log in and view all pages but cannot make changes.

Step-by-Step: Enable a Feature

  1. Navigate to Settings > Global Options
  2. Find the feature you want to enable (e.g. api_armor_enabled)
  3. Toggle it on
  4. Review any dependency warnings
  5. Save and Apply Changes

Step-by-Step: Create a Custom Theme

  1. Navigate to Settings > Appearance
  2. Click Create Custom Theme
  3. Select a built-in theme to clone from (e.g. Dracula)
  4. Name your theme (e.g. My Custom Dark)
  5. Adjust colors using the color pickers:
    • Background colors
    • Border colors
    • Text colors
    • Semantic colors (primary, secondary, accent)
    • Status colors (success, warning, error, info)
  6. Preview the changes live
  7. Click Save
  8. Select your custom theme from the theme picker

Verification

  1. Test login:

    curl -k -X POST https://localhost/api/v1/auth/login -H "Content-Type: application/json" -d '{"username":"admin","password":"your-password"}'

    Expect a JWT token in the response.

  2. Test 2FA:

    • Enable 2FA on your account
    • Log out and log back in
    • Verify the TOTP code is required

  3. Test read-only role:

    • Log in as the read-only user
    • Attempt to create a backend
    • Expect a 403 Forbidden response

  4. Test theme switching:

    • Switch between built-in themes
    • Verify the UI updates immediately
    • Refresh the page and verify the theme persists

Next Steps

← Previous Audit & Snapshots Next → MCP Gateway