Skip to main content

Users

The Users page manages user accounts for accessing GEM. Each user has authentication credentials, role assignments, and notification preferences.

Overview​

User accounts control access to GEM's web interface, mobile apps, and API. Users can be assigned multiple roles, restricted to specific sites, and configured with notification profiles.

Viewing Users​

The main grid displays all user accounts with the following columns:

  • ID - Unique user identifier
  • Username - Login username
  • Email - Email address for notifications
  • SMS - Phone number for SMS notifications
  • Roles - Assigned roles (displayed as comma-separated list)
  • Enabled - Whether the account is active

Grid Actions​

  • Add - Create a new user account
  • Edit - Modify an existing user
  • Reload - Refresh the grid data

User rows cannot be deleted from this grid — disable the account instead (clear Enabled or set Revoked) so audit history is preserved. Visitors are managed from the dedicated Visitors page.

Creating a User​

To create a new user account:

  1. Click Add in the grid toolbar
  2. Configure the user properties (see sections below)
  3. Click Save

User Configuration​

The user editor is organized into several sections:

Basic Information​

First Name / Last Name

  • Optional human-readable name fields
  • Used in access logs, visitor host selectors, and printed visitor badges
  • First Name is the canonical input; Last Name is optional

Photo

  • Optional headshot for the user
  • Click Upload to pick an image file (max 1 MB) or Take Photo to capture from the device webcam
  • Stored on the user record and printed on visitor badges when this user is selected as a Host
  • Click Remove to clear the existing photo
  • When Facial Recognition is enabled, the photo is auto-embedded locally (YuNet + MobileFaceNet) and the resulting 512-D embedding is stored encrypted as the facial_recognition_embedding attribute. If no face is detected, facial_recognition_embedding_error records the reason. Per-user opt-out is the facial_recognition_enabled attribute (defaults to true once the system-wide toggle is on).

Username

  • Internal identifier (lowercase_with_underscores)
  • Used for login
  • Cannot be changed after creation (tied to audit logs)
  • Examples: john_smith, admin, installer_1

Email

  • Email address for notifications
  • Optional but recommended
  • Used for password reset (if implemented)
  • Validated format

SMS

  • Phone number for SMS notifications
  • Optional
  • Format: +1234567890 (include country code)
  • Used with notification profiles

Security​

Password

  • Check "Change Password" to set a new password
  • Input field activates when checkbox is checked
  • Minimum length: 8 characters (configurable)
  • Requirements:
    • Recommended: Mixed case, numbers, symbols
    • Stored as bcrypt hash
    • Never displayed or logged in plain text

PIN

  • Check "Change PIN" to set a numeric PIN
  • Used for:
    • Mobile app quick access
    • Keypad entry
    • Access control devices
  • 4-6 digit numeric code
  • Stored encrypted
  • PINs must be unique across all users (including disabled accounts) — the server rejects a save that collides with another user's PIN so keypad entry resolves to a single account

Duress PIN

  • Check "Change duress PIN" to set a per-user silent panic code
  • Granting access uses the user's regular PIN; entering the duress PIN also grants access but additionally fires the access rule's Duress Macro (e.g. arm panic alarm, push notification to security)
  • The attacker sees normal door behavior — there is no UI feedback that distinguishes the duress code
  • Duress PINs are uniqueness-checked against every other user's pin, rfid, and duress_pin to prevent collisions

Credential Lifecycle

  • Valid From — credentials grant access only at or after this time (optional)
  • Valid Until — after this time, access is denied at the door and the user is auto-disabled on every linked access device on the next 15-minute sweep, so cached PINs on devices like 2N intercoms are also revoked
  • Revoked — hard stop; overrides any valid window. Re-enabling (clearing this checkbox) automatically re-syncs credentials to all access devices the user has rights on.

Use these for contractor/visitor access without having to remember to manually disable the user when their term ends.

Two-Factor Authentication

  • Toggle to require 2FA for this user
  • When enabled, user must verify login with:
    • SMS code (if SMS configured)
    • Email code (if email configured)
    • Authenticator app (if configured)

Session Timeout

  • Session timeout in minutes
  • 0 = No automatic timeout
  • Recommended: 60-480 minutes (1-8 hours)
  • User must re-authenticate after timeout

Roles​

Assign one or more roles to the user:

  • Roles define permissions (UIs, routes, API functions)
  • Multiple roles combine permissions (additive)
  • Common roles:
    • admin - Full system access
    • user - Standard user access
    • installer - Installation and commissioning
    • viewer - Read-only access
    • api_only - API access only (no UI)

See Roles for detailed role configuration.

Role Assignment:

  • Check all roles that apply
  • Roles are displayed in a checkbox grid
  • Changes take effect on next login

Sites​

Restrict user access to specific sites:

  • Leave empty for access to all sites
  • Select specific sites to limit access
  • Useful for:
    • Multi-tenant installations
    • Multi-site enterprises
    • Service provider accounts

See Sites for site configuration.

Notification Profile​

Assign a notification profile:

  • Defines when and how user receives notifications
  • Includes:
    • Email, SMS, and Web Push channel toggles
    • Active days (day-of-week schedule)
    • Active hours (hour-of-day schedule)

See Notification Profiles for details.

Additional Settings​

Account Status (Enabled)

  • Toggle to enable/disable the account
  • Disabled users cannot log in
  • Preserves all configuration and history

User Status​

User accounts can be in different states:

Active​

  • Enabled = Yes
  • Can log in and access permitted resources
  • Shown with green "Active" badge

Inactive​

  • Enabled = No
  • Cannot log in
  • Configuration preserved
  • Shown with red "Inactive" badge

Locked (Future)​

  • Account locked after failed login attempts
  • Requires admin to unlock

Security Best Practices​

Password Management​

  1. Strong Passwords: Enforce minimum complexity
  2. Regular Changes: Encourage periodic password updates
  3. No Sharing: Each person should have their own account
  4. Service Accounts: Use dedicated accounts for integrations

Role Assignment​

  1. Least Privilege: Assign minimum necessary permissions
  2. Role Segregation: Separate admin, installer, and user roles
  3. Review Regularly: Audit role assignments quarterly
  4. Remove Unused: Delete or disable accounts no longer needed

Two-Factor Authentication​

  1. Enable for Admins: Always require 2FA for admin accounts
  2. Remote Access: Require 2FA for remote/internet access
  3. Sensitive Operations: Consider 2FA for critical changes

Session Management​

  1. Appropriate Timeouts: Balance security and convenience
    • Admin accounts: 60-120 minutes
    • User accounts: 240-480 minutes
    • Kiosk/public: 5-15 minutes
  2. Automatic Logout: Enable for unattended sessions
  3. Single Session: Consider limiting concurrent logins

Monitoring​

  1. Login Tracking: Review access logs regularly
  2. Failed Attempts: Monitor for brute force attacks
  3. Unusual Activity: Investigate unexpected access patterns
  4. Audit Changes: Track who modified what configuration

Common Workflows​

Creating an Admin User​

  1. Click Add
  2. Set username: admin
  3. Set strong password
  4. Check admin role
  5. Enable Two-Factor Authentication
  6. Set Token Duration: 120 minutes
  7. Click Save

Creating a Standard User​

  1. Click Add
  2. Set username: homeowner_name
  3. Enter email for notifications
  4. Set password
  5. Check user role
  6. Select appropriate sites (if multi-site)
  7. Assign notification profile
  8. Click Save

Creating an Installer Account​

  1. Click Add
  2. Set username: installer_company
  3. Set temporary password
  4. Check installer role
  5. Set Token Duration: 480 minutes (8 hours)
  6. Enabled: Yes
  7. Click Save
  8. Provide credentials to installer
  9. Disable account when commissioning complete

Creating an API Service Account​

  1. Click Add
  2. Set username: api_integration_name
  3. Set strong password (or generate random)
  4. Check api_only role
  5. Token Duration: 0 (no timeout)
  6. Do NOT assign notification profile
  7. Click Save
  8. Use credentials in API integration

Resetting a Password​

  1. Edit the user
  2. Check Change Password
  3. Enter new password
  4. Click Save
  5. Notify user of password change

Disabling a User Account​

  1. Edit the user
  2. Set Enabled: No
  3. Click Save
  4. User immediately loses access

Granting Temporary Access​

  1. Create user with appropriate roles
  2. Set Enabled: Yes
  3. Document expiration date
  4. On expiration date, set Enabled: No

User Account Limitations​

Username Restrictions​

  • Cannot change username after creation
  • Username must be unique
  • Lowercase with underscores only
  • No special characters except underscore

Deletion Restrictions​

  • The Users grid does not expose a delete action — disable the account instead (clear Enabled or set Revoked) so audit history stays intact
  • User ID 0 is a seeded system sentinel and cannot be removed
  • Visitors auto-expire via their valid_until window — see Visitors

System Accounts​

  • User ID 0: Internal system user
  • Cannot be deleted or disabled
  • Used for automated processes
  • No login access

Authentication Methods​

Password Authentication​

  • Default method for web interface
  • bcrypt hashing with configurable rounds
  • Password stored as hash only

PIN Authentication​

  • Used for mobile app quick access
  • Used with keypad devices
  • Numeric only (4-6 digits)
  • Less secure than password

Token Authentication​

  • API requests use token-based auth
  • Tokens generated on login
  • Tokens expire based on Token Duration
  • Tokens invalidated on logout

Two-Factor Authentication​

When enabled:

  1. User enters username/password
  2. System sends verification code via SMS or email
  3. User enters code to complete login
  4. Code expires after 10 minutes
  5. Limited retry attempts

Permissions and Access Control​

User permissions are determined by:

  1. Roles: Define what resources user can access
  2. Sites: Limit user to specific sites
  3. Enabled Status: Must be enabled to access anything

Permission Evaluation:

Can Access = Enabled AND (Sites Match OR Sites Empty) AND Roles Allow

See Roles for detailed permission configuration.

Troubleshooting​

User Cannot Log In​

Check:

  1. Enabled Status: Ensure account is enabled
  2. Password: Verify password is correct
  3. Roles: Ensure user has at least one role with login permission
  4. Sites: If sites are configured, verify current site matches
  5. Network: Check if firewall is blocking access
  6. Logs: Review access logs for error messages

User Has Wrong Permissions​

Check:

  1. Roles: Verify correct roles are assigned
  2. Role Rules: Check role configuration in Roles page
  3. Sites: Verify site restrictions if applicable
  4. Cache: User may need to log out and back in

Two-Factor Not Working​

Check:

  1. Email/SMS: Verify contact information is correct
  2. Delivery: Check email spam folder or SMS delivery
  3. Code Expiry: Codes expire after 10 minutes
  4. Retry Limit: Too many failed attempts may lock verification

Session Expires Too Quickly​

Solution:

  1. Edit user
  2. Increase Token Duration
  3. Click Save
  4. User must log in again for new timeout to apply

Removing a User​

The Users grid does not have a delete action by design — deleting a user would orphan access logs, audit history, and access-control references. Instead:

  1. Edit the user
  2. Clear Enabled, or set Revoked under Credential Lifecycle
  3. Click Save

The account immediately loses access (revoked credentials propagate to access devices), but history and references stay intact.