Access Control

The Access Control page manages physical access control rules that link user credentials (PINs, RFID cards) to automated actions, as well as credential-free exit triggers (REX). When a valid credential is presented to an access device, or a REX input is triggered, GEM executes configured commands or macros.

Overview

Access Control enables:

• Physical Security Integration: Link door locks, gates, and keypads to GEM
• Credential Management: Associate user PINs and RFID cards with actions, with valid-from / valid-until / revoked lifecycle
• Request to Exit (REX): Trigger actions from exit buttons or sensors without credentials
• Call Buttons / Doorbells: Log + snapshot + optional action when a visitor presses an intercom call button — no credential required
• Automated Responses: Unlock doors, run macros, trigger scenes — or log only
• Time-Based Access: Restrict access by day, hour, exception dates, and shared holiday calendars
• User-Specific Actions: Different users can trigger different actions
• Access Groups & Roles: Authorize groups of users or anyone holding a specific role
• Cooldown: Prevent repeated triggers within a configurable time window
• Lockdown Mode: System-wide kill-switch that restricts access to opt-in rules (REX always works for fire egress)
• Duress PIN: A second PIN per user that grants access and fires a silent panic action
• Centralized Device Sync: Disabled, expired, or revoked users are automatically removed from access devices that support a sync API (e.g. 2N intercoms)

Viewing Access Control Rules

The main grid displays all configured access control rules with the following columns:

• ID - Unique rule identifier
• Name - Internal rule name
• Description - Rule description
• Users - Authorized users (comma-separated usernames)
• Access Device - Device that receives credentials
• Type - Credential type (PIN, RFID, REX, or Call)
• Action - What happens on successful authentication (or "Log Only")
• Enabled - Whether the rule is active
• Days - Active days summary (e.g., "Every day", "Weekdays", or individual days)
• Hours - Active hours summary (e.g., "24h", "8:00–17:00")
• Last Triggered - Timestamp of the most recent trigger

Grid Actions

• Add - Create a new access control rule
• Edit - Modify an existing rule
• Duplicate - Copy an existing rule (click the copy icon in the row)
• Delete - Remove a rule
• Reload - Refresh the grid data

Creating an Access Control Rule

To create a new rule:

1. Click Add in the grid toolbar
2. Configure the rule (see sections below)
3. Click Save Access Rule

Rule Configuration

Basic Information

Rule Name

• Internal identifier (lowercase_with_underscores)
• Examples: front_door_access, garage_entry, admin_gate
• Auto-formatted on change

Description

• Human-readable description
• Examples: "Front door access for family", "Garage opener for residents"
• Helps document rule purpose

Status

• Toggle to enable/disable the rule
• Disabled rules:
  • Do not process credentials
  • Remain configured for later re-enablement
  • Shown with "Disabled" indicator

Access Configuration

Access Device

• Select the device that will receive credentials
• Common devices:
  • Keypads (PIN entry)
  • RFID readers (card/fob readers)
  • Biometric readers
  • Mobile credential readers
• Device must be configured in System > Devices

Access Type

• PIN Code: Numeric PIN entered on keypad
• RFID Card: Card/fob presented to reader
• Request to Exit (REX): Triggered by an exit button, motion sensor, or other input on the access device — no credential or user required
• Call Button / Doorbell: Triggered when a visitor presses the call button on an intercom or doorbell — no credential or user required. The event is logged with reason='call_button' and a snapshot is captured (facial-recognition pipeline still gets a shot at identifying the visitor). Use the optional action to ring a chime macro, send a push notification, or open a video preview.

Action Type

• Device Command: Execute a specific command
• Run Macro: Execute a macro (for complex sequences)
• None (Log Only): No action is performed — the event is logged only. Useful for monitoring access without triggering a device or macro.

Cooldown (seconds)

• Minimum time between repeated triggers for this rule
• For PIN/RFID rules, cooldown is tracked per-user
• For REX rules, cooldown applies globally to the rule
• Set to 0 to disable (default)
• Duress codes always bypass cooldown so a panicking user mashing the keypad still triggers the alarm

tip

For denied-access notifications, attach an Attribute Trigger to the access device's last_access_result attribute (set to denied on every failed attempt). This composes with the rest of the trigger system — schedule, debounce, notification profile selection — instead of being a per-rule one-off.

Authorized Users

Select Users

• Multi-select list of users who can authenticate
• Selected users' credentials will be accepted
• User must have PIN or RFID configured (in Users page)
• Changes require users to re-sync credentials

note

REX and Call Button rules do not require user selection. They are credential-free events (a push-to-exit button or an intercom call button) — no user matching is performed, and the configured action (if any) executes immediately when the device signals the event.

Access Groups

For PIN/RFID rules, you can authorize users via Access Groups in addition to individual user selection. Members of any selected group are authorized alongside individually selected users.

• Select one or more access groups from the multi-selector
• Group membership is evaluated at access time (adding a user to a group immediately grants access)
• Access groups are not available for REX rules

Roles

Authorization can also be granted by Role. Anyone holding a selected role is authorized — useful for "anyone with the maintenance role can enter the boiler room" rules without maintaining a parallel user list.

• Roles, groups, and individual user lists are evaluated as a union (any path grants access)
• Removing a role from a user immediately removes their access

How It Works:

1. User enters PIN or presents RFID at access device (or REX input is triggered)
2. Device sends credential (or REX signal) to GEM
3. For PIN/RFID: GEM checks if credential matches any authorized user
4. For REX: GEM executes the action immediately (no user matching)
5. If match found and schedule allows, action is executed

Action Configuration

Device Command

When action type is "Device Command":

Command Configuration:

• Device: Select target device (lock, gate, etc.)
• Zone: Select specific zone if applicable
• Command: Choose command (unlock, open, etc.)
• Parameters: Set any command parameters

Example:

Device: front_door_lock
Zone: front_door
Command: unlock
Duration: 5 seconds

Run Macro

When action type is "Run Macro":

Select Macro:

• Choose macro from dropdown
• Macro can include multiple steps:
  • Unlock door
  • Turn on lights
  • Disarm security
  • Send notification
  • Any automation sequence

Example Macro: "Arrive Home"

Step 1: Unlock front door
Step 2: Turn on entry lights
Step 3: Disarm security system
Step 4: Set HVAC to home mode
Step 5: Send notification: "User arrived home"

Schedule Configuration

Restrict when the access control rule is active:

Days of Week

Select which days the rule is active:

Quick Select Buttons:

• All Days: Enable all 7 days
• No Days: Disable all days (useful for testing)
• Weekdays: Monday-Friday
• Weekends: Saturday-Sunday

Individual Days:

• Check/uncheck each day: Sun, Mon, Tue, Wed, Thu, Fri, Sat

Use Cases:

• Weekdays only: Service personnel
• Weekends only: Weekend guests
• All days: Residents

Hours of Day

Select which hours the rule is active:

Quick Select Buttons:

• All Hours: Enable all 24 hours
• No Hours: Disable all hours
• Business Hours: 8 AM - 5 PM (hours 8-17)
• Night: 8 PM - 5 AM (hours 20-23, 0-5)

Individual Hours:

• Check/uncheck each hour (24-hour format)
• Hour 0 = 12:00 AM - 12:59 AM
• Hour 13 = 1:00 PM - 1:59 PM
• etc.

Use Cases:

• Business hours only: Cleaning crew
• Night hours only: Security patrol
• All hours: Residents

Schedule Exceptions

Block access on specific dates, regardless of the day/hour schedule:

• Add exception dates using the date picker and Add button
• On an exception date, the rule will not grant access even if the day and hour would normally allow it
• Remove an exception by clicking the × next to the date
• Exceptions are sorted chronologically
• Use cases: ad-hoc maintenance windows, special events

Holiday Calendar

For dates shared across many rules — federal holidays, company shutdowns — assign a Holiday Calendar to the rule. Holiday calendars are managed in Security > Holiday Calendars and can contain individual dates or ranges (from–to).

• Calendar dates are evaluated before the day/hour mask — a holiday wins
• One calendar can be referenced by many rules, so you only have to update holidays in one place
• Per-rule exception dates and the calendar both apply (denied if either matches)

Lockdown & Duress

Allow During Lockdown

When the system is in lockdown, only rules with this flag enabled fire. REX and Call Button rules are exempt by default — REX for fire-egress safety, Call Button so visitors can still be logged and seen during a lockdown. Either exemption can be removed per-rule by clearing Allow During Lockdown. Useful for emergencies, after-hours, or partial lockouts.

• Activate or clear lockdown from the banner at the top of the Access Control page
• Lockdown is stored as a system attribute (access_lockdown), so it can also be toggled from a macro (e.g. tied to an alarm panel state, panic button, or automation rule)

Duress Macro

Each rule can specify a duress macro that fires silently when a user enters their duress PIN (configured per-user in Users). The normal action still runs (door unlocks) so the attacker doesn't realise. The duress event is logged with reason='duress' for the audit trail.

• Typical duress macros: arm panic alarm, push notification to security, dial guard, capture extra snapshots
• Duress codes bypass cooldown so a panicking user mashing the keypad still triggers the alarm

Held-Open Threshold (s)

Setting this to a non-zero value enables unauthorized-open and held-open detection for the rule's target zone:

• Unauthorized open (logged as result='forced', reason forced_door) — the door's contact transitions to opened without an authorized unlock in the last 10 seconds. This is an inference — we don't know the door was physically forced; we only know GEM didn't see a recent unlock. Treated as worth flagging, but not asserted as ground truth: an access_log entry is written and a notification fires, but no zone attribute is set (avoids overclaiming).
• Held-open (result='held_open') — once the door has opened, GEM starts a timer for held_open_threshold_sec. If the contact hasn't returned to closed by then, an entry is logged (with snapshot + notification) and the door zone gets held_open=true set as a state attribute. The timer re-arms so a propped door keeps reminding rather than going silent after one alert. When the door physically closes, held_open clears back to false. This one is a measurement, so the zone attribute is appropriate — dashboard widgets, attribute_triggers, and macros can react to it directly.

Two zone attributes are written:

• held_open (bool) — current state. true while the door is held open past the threshold, false once it closes.
• last_held_open_at (datetime) — point-in-time timestamp of the most recent occurrence; persists across closes so history queries can find it.

The detection uses the door zone's existing state attribute (driven by your contact sensor) — no extra wiring or pairing fields. Manual unlocks (admin UI, macros, automation) refresh the grace window automatically when the lock zone state transitions to unlocked.

Set the threshold to 0 (or leave blank) to disable monitoring — useful for rules that just log an event without owning a physical door (e.g. an audit-only rule on a device that's already monitored by another rule).

Common Use Cases

Front Door - Family Access

Name: front_door_family
Description: Family members unlock front door
Access Device: front_door_keypad
Access Type: PIN Code
Authorized Users: mom, dad, teen_son, teen_daughter
Action Type: Device Command
  Device: front_door_lock
  Command: unlock
  Duration: 5 seconds
Days: All Days
Hours: All Hours
Status: Enabled

Gate - Service Personnel

Name: gate_service
Description: Service personnel gate access during business hours
Access Device: front_gate_reader
Access Type: RFID Card
Authorized Users: lawn_service, pool_service, housekeeper
Action Type: Device Command
  Device: front_gate
  Command: open
  Duration: 30 seconds
Days: Weekdays (Mon-Fri)
Hours: Business Hours (8 AM - 6 PM)
Status: Enabled

Garage - Arrive Home Macro

Name: garage_arrive_home
Description: Activate arrive home scene
Access Device: garage_keypad
Access Type: PIN Code
Authorized Users: homeowner, spouse
Action Type: Run Macro
  Macro: arrive_home (unlocks door, lights on, disarm security)
Days: All Days
Hours: All Hours
Status: Enabled

Office - Employee Access

Name: office_employee
Description: Office door access for employees
Access Device: office_door_reader
Access Type: RFID Card
Authorized Users: employee_1, employee_2, employee_3
Action Type: Device Command
  Device: office_door_lock
  Command: unlock
  Duration: 3 seconds
Days: Weekdays
Hours: 6 AM - 10 PM
Status: Enabled

Temporary Guest Access

Name: guest_access_weekend
Description: Weekend guest access to pool gate
Access Device: pool_gate_keypad
Access Type: PIN Code
Authorized Users: weekend_guest
Action Type: Device Command
  Device: pool_gate
  Command: unlock
Days: Saturday, Sunday
Hours: All Hours
Status: Enabled (disable after guest departs)

Request to Exit (REX)

Name: front_door_rex
Description: Exit button unlocks front door from inside
Access Device: front_door_intercom
Access Type: Request to Exit (REX)
Authorized Users: (none required)
Action Type: Device Command
  Device: front_door_lock
  Command: unlock
  Duration: 5 seconds
Days: All Days
Hours: All Hours
Status: Enabled

How Access Control Works

System Flow

1. Credential Presentation or REX Trigger:

   • User enters PIN on keypad, or
   • User presents RFID card to reader, or
   • REX input is activated (exit button, motion sensor, etc.)

2. Device to GEM:

   • Access device sends credential or REX signal to GEM via:
     • TCP/IP
     • Serial
     • Integration protocol (Wiegand, etc.)

3. Rule Matching:

   • GEM receives the event
   • Searches access control rules for matching:
     • Access device
     • Access type
     • Enabled status
     • Current day (schedule check)
     • Current hour (schedule check)

4. User Matching (PIN/RFID only):

   • If rule found, check authorized users and access groups
   • Compare credential to each user's stored PIN/RFID
   • User must be in the authorized user list or a member of an authorized access group
   • If match found, proceed to schedule and cooldown checks
   • REX rules skip this step entirely

5. Schedule & Cooldown Check:

   • Verify current day/hour is within the rule's schedule
   • Check exception dates — deny if today is an exception
   • Check cooldown — deny if the user (or REX rule) triggered too recently

6. Action Execution:

   • Execute configured command, macro, or log only
   • Log access event (REX events are logged with reason rex)
   • Record last triggered timestamp on the rule
   • Send notifications if configured

7. Access Denied (PIN/RFID only):

   • If no match, schedule invalid, or cooldown active:
     • Log denied access attempt with reason
     • Update the access device's last_access_result / last_access_reason / last_access_user / last_access_at attributes, and increment failed_access_count
     • Denial reasons: unknown_credential, user_not_authorized, schedule_mismatch, cooldown, lockdown
     • Hook an Attribute Trigger to last_access_result == 'denied' (or failed_access_count > N) to send notifications

Credential Storage

PIN Codes:

• Stored in user record (AES-256-GCM encrypted)
• Set in Security > Users page
• 4-6 digit numeric (longer recommended)

Duress PIN:

• A second per-user PIN that also grants access but fires the rule's duress macro silently
• Must be unique across the entire user base — including other users' regular PINs

RFID Cards:

• Stored as card ID in user record (AES-256-GCM encrypted)
• Typically 8-16 character hex string
• Format depends on reader (Wiegand-26, Wiegand-37, etc.)
• Set in Security > Users page

Credential Lifecycle

Each user has three lifecycle fields that gate physical access:

• Valid From — credentials grant access only at or after this time
• Valid Until — after this time, access is blocked at the door and GEM auto-disables the user on every linked access device (so cached PINs on devices like 2N intercoms are also revoked)
• Revoked — hard stop, overrides any valid window

The expiry sweep runs every 15 minutes. Re-enabling a user (clearing revoked or extending Valid Until) automatically re-syncs credentials to the access devices the user has rights on.

Device Integration

Access devices must be configured in System > Devices:

Keypad Devices:

• Driver: Device-specific (e.g., linear_keypad, doorking_keypad)
• Connection: Serial, TCP/IP, or wireless
• Attributes: Communication settings

RFID Readers:

• Driver: Device-specific (e.g., hid_reader, generic_wiegand)
• Connection: Wiegand, serial, TCP/IP
• Attributes: Format, bit length

Example Device Configuration:

Name: front_door_keypad
Driver: linear_keypad
Connection Type: Serial
Port: /dev/ttyUSB0
Baud: 9600
Enabled: Yes

Image Capture

GEM captures snapshots of access events using a fallback chain:

1. External camera device — set camera_device_id on the access device to point to a camera/NVR device. Optionally set camera_address for multi-camera NVRs.
2. Device image download — if the access device supports image download natively (e.g., 2N intercoms), GEM calls it directly.
3. Device snapshot command — as a final fallback, GEM sends a snapshot command to the access device itself.

When a snapshot is captured, the Access Log shows a camera icon on each event to retrieve the image.

Reactive attributes on the access device

Every access event also writes a small set of attributes onto the access device itself, so dashboards, attribute_triggers, and macros can react without polling the access_log:

Attribute	Type	Set when
last_access_result	string	Every event — granted, denied, duress, forced, held_open, or error
last_access_reason	string	Every event — e.g. success, unknown_credential, cooldown, schedule_mismatch, lockdown, duress, held_open
last_access_user	string	Every event — username, or empty for unknown credentials
last_access_at	string	ISO timestamp of the most recent attempt
failed_access_count	int	Consecutive denied attempts since the last grant. Resets to 0 on granted or duress; increments on denied. Physical events (forced, held_open) leave the counter alone.

Pair them with Attribute Triggers for things like "alert me when failed_access_count crosses 5" or "open the gate camera when last_access_result == 'forced'".

Security Considerations

Credential Security

1. Unique PINs & RFIDs: GEM enforces uniqueness across all users (including disabled accounts) when a PIN or RFID is saved — a collision is rejected so keypad / reader input resolves to a single user
2. PIN Length: Minimum 4 digits, recommend 6+
3. Rotation: Encourage regular PIN changes
4. RFID Encryption: Use encrypted RFID formats when available

Access Logging

1. All Events: Log both granted and denied access
2. Audit Trail: Include timestamp, user, device, action
3. Retention: Retain logs per compliance requirements
4. Monitoring: Review logs regularly for anomalies

See Insights > Access Log for access event logs.

Failed Access Attempts

Consider implementing:

1. Lockout: Disable rule after X failed attempts
2. Alerts: Notify on failed access attempts
3. Delay: Add increasing delay after failures
4. Monitoring: Flag users with multiple failures

Temporary Access

For temporary users (guests, contractors):

1. Create user with PIN/RFID
2. Create dedicated access control rule
3. Configure appropriate schedule
4. Important: Disable rule when access period ends
5. Delete or disable user account
6. Consider time-limited credentials (via macro)

Remote Access

Warning: Access control can grant physical access remotely.

Best Practices:

1. Require 2FA for users who can modify access control
2. Restrict "Access Control" page to admin role only
3. Audit changes to access control rules
4. Log all remote access control operations

Troubleshooting

Credential Not Working

Check:

1. Rule Enabled: Verify access control rule is enabled
2. User in List: Confirm user is in authorized users list
3. Credential Match: Verify PIN/RFID in user record matches
4. Schedule: Check current day and hour are enabled
5. Device: Ensure access device is online and working
6. Logs: Review access log for denied attempts

Action Not Executing

Check:

1. Device Online: Verify target device (lock, gate) is online
2. Command Valid: Test command independently
3. Macro: If using macro, verify macro works
4. Logs: Check system logs for errors
5. Permissions: Ensure GEM can control target device

tip

When you reload an access device via System > Devices, its access control rules are automatically re-attached. No server restart is needed.

Schedule Not Working

Check:

1. Time Zone: Verify GEM server time zone is correct
2. Server Time: Confirm server time is accurate
3. Day Mask: Verify correct days are checked
4. Hour Mask: Verify correct hours are checked
5. All Days/Hours: Try enabling all to test

Multiple Users, Same Action

Expected Behavior:

• One access control rule can have multiple authorized users
• All users trigger the same action
• To have different actions per user:
  • Create separate access control rules
  • Each rule has one user
  • Each rule has different action

RFID Not Reading

Check:

1. Reader Power: Ensure reader has power
2. Reader Connection: Verify communication to GEM
3. Card Format: Check card format matches reader
4. Card ID: Verify card ID is correctly stored in user record
5. Read Distance: Hold card closer/longer

Advanced Topics

Multi-Device Access

For locations with multiple entry points:

1. Create separate access device for each entry point
2. Create separate access control rules per device
3. Assign same users to multiple rules
4. Different schedules or actions per entry point

Example:

Front Door: All users, all hours
Back Door: Family only, no guests
Garage: Family + service, scheduled

Cascading Actions

Use macros for complex entry sequences:

Example: "Security Bypass Entry"

User enters PIN at front door:
  1. Disable security alarm (30 second bypass)
  2. Unlock front door (5 second unlock)
  3. Turn on entry lights (stay on)
  4. Send notification: "User entered via front door"
  5. Wait 30 seconds
  6. If security not disarmed, trigger alarm

Integration with Security Systems

Coordinate with security panels:

1. Disarm on Entry: Use macro to disarm when valid credential
2. Arm on Exit: Last person out triggers arm macro
3. Bypass Zones: Temporarily bypass entry zones
4. Alert on Invalid: Multiple failed attempts trigger alert

Conditional Access

Implement conditional logic via macros:

Example: "Mode-Based Access"

If home_mode = "vacation":
  - Deny access even if credential valid
  - Send alert: "Access attempt during vacation mode"
Else:
  - Grant access normally

Access Level Hierarchies

Create tiered access using multiple rules:

Level 1 - Resident Access:

• All entry points
• All times
• All days

Level 2 - Service Access:

• Service entrance only
• Business hours
• Weekdays only

Level 3 - Guest Access:

• Guest entrance only
• Limited hours
• Specific dates

Driver Contract for Access Devices

Drivers participate in centralized user sync by exposing any subset of the following methods. The access control engine duck-types each call, so a driver that only implements one method still works.

Method	Purpose
async syncUser(userId, user)	Push or update the user's current credentials on the device. Driver decrypts as needed.
async disableUser(userId)	Block the user without removing them. Preferred when the device supports a disabled state.
async deleteUser(userId)	Remove the user entirely. Used as a fallback when no disableUser exists.
async listUsers()	Return current users on the device (for reconciliation).

The engine prefers disableUser over deleteUser so credential history is preserved when possible. Reference implementations:

• 2N HTTP intercoms — lib/drivers/2n_http.js. LAN-resident, syncs PIN/card credentials over HTTPS to the unit's directory API. Day/hour schedules from the rule (day_enable_mask + hour_enable_mask) are projected onto each user as inline 2N time profiles on accessPoints[].profiles, so the device enforces day/hour windows offline without GEM in the loop. Multi-rule users get the union of their windows; if every rule excludes the current time the user's accessPoints[].enabled is set to false for safe offline denial. The device's pre-numbered Profile slots (P=0..19) are not touched, so any profiles configured manually on the device remain intact. If your firmware rejects Basic auth on directory writes, set the device's auth_method attribute to digest to match the device-side HTTP API account setting.
• Brivo cloud access control — lib/drivers/brivo.js. Cloud-resident, OAuth2-authenticated, ingests events via Brivo event-subscription webhooks (with polling fallback). See Brivo integration docs.

Related Documentation

• Users - Managing user PINs, RFID cards, duress codes, and credential lifecycle
• Access Groups - Managing reusable groups of users for access rules
• Holiday Calendars - Shared date sets for blocking access across rules
• Roles - Role-based authorization
• Macros - Creating access automation sequences (duress, lockdown, etc.)
• Devices - Configuring access control devices
• Access Log - Monitoring access events
• Notification Profiles - Configuring denied-access alerts
• Triggers - Advanced access automation