Skip to main content

Access Log

The Access Log page displays detailed records of all physical access control events, including PIN entries, RFID card presentations, and the results of access attempts.

Overview​

Access Log provides:

  • Real-Time Updates: Live log of access events
  • Detailed Records: Who, when, where, and result
  • Filtering: By user, device, type, result, date
  • Security Auditing: Track granted and denied access
  • Export: Generate reports for compliance

Viewing Access Events​

The main grid displays all access log entries:

Columns:

  • ID: Unique log entry identifier
  • Timestamp: When access was attempted
  • User: Which user attempted access
  • Access Device: Which device received credential
  • Access Type: PIN, RFID, or REX
  • Result: Granted, Denied, Duress, Forced, Held Open, or Error
  • Action Details: What action was executed (if granted)
  • Reason: Detail behind the result (e.g. success, unknown_credential, cooldown, lockdown, duress, forced_door, held_open)
  • Match: Optional facial-recognition match score for the event (see Facial Recognition below). Empty when scoring is disabled or did not run.

Image / Video Capture​

Each log row includes a camera icon button. Clicking it opens a modal showing an image (or short video clip, for cloud drivers like Brivo) from the time of the access event.

Snapshot Sources:

GEM checks for snapshots in this order:

  1. Stored snapshot — If the access log record has a snapshot stored directly (e.g., captured at the time of the event by the access device driver), it is displayed immediately. The stored value can be either a base64 data URI (image bytes) or a fully-qualified https://… URL pointing at a recording (e.g. Brivo S3-hosted clip).
  2. NVR on-demand lookup — If no stored snapshot exists, GEM retrieves one from the associated NVR using the access device's attributes:
    • nvr_device_id — ID of the NVR device (e.g., an Axis Camera Station device)
    • nvr_camera — camera/video source identifier on the NVR
    • The NVR device must support the snapshot command with a date_time parameter

Snapshot Modal:

  • Inline images render as <img>
  • URLs ending in .mp4, .webm, .mov, .m4v, .m3u8, or .ts (or with a video/* MIME) render as a <video> player with autoplay/controls — used by Brivo clip URLs
  • For NVR snapshots, the camera name and source type (recording or live) are shown above the image
  • If no snapshot is available from either source, an error message is displayed
tip

For Axis Camera Station, cameras are auto-discovered as zones. Use the zone's address as the nvr_camera attribute value on the access device.

Facial Recognition​

When enabled, GEM compares the user's profile photo against the snapshot captured at each access event and records an advisory match score on the log row. All processing is local — face detection and embedding inference run entirely on this server using bundled open-source models (YuNet detector + MobileFaceNet embedder). Profile photos and biometric embeddings never leave the installation.

Enabling​

Two opt-in toggles must both be on for an event to be scored:

  1. System-wide — set the facial_recognition_enabled system attribute to true. Off by default.
  2. Per-user — each user has a facial_recognition_enabled attribute that defaults to true once the system-wide setting is enabled. Users (or admins on their behalf) can flip it to false to opt the user out without removing their photo.

A user's profile photo (the image field on auth_user) is automatically embedded when uploaded or changed; the resulting 512-D embedding is stored encrypted as the user's facial_recognition_embedding attribute. If the photo doesn't contain a detectable face, facial_recognition_embedding_error records the reason (e.g. no_face_detected) so the admin knows to upload a clearer photo.

Match Column​

The Match column shows one of:

  • ✓ NN% (green badge) — match score ≥ 50%. Same person, high confidence.
  • ⚠ NN% (amber badge) — score 30–50%. Ambiguous, often caused by poor snapshot quality, bad lighting, or partial face.
  • ✕ NN% (red badge) — score < 30%. Likely a different person than the credential's owner.
  • off — system-wide toggle is disabled.
  • opt-out — user opted out.
  • no photo — user has no usable embedding (no profile photo, or photo had no detectable face).
  • no face — face was not detected in the event snapshot (dark, blurry, person walked past, etc.).
  • — — no auth_user_id on the event (anonymous credential or unknown PIN).
  • error — pipeline failure; see server logs.

These bands are starting points, not guarantees. Calibrate against your own population by reviewing a week of scores after enabling — if the green band is producing too many ambiguous results, raise the threshold; if mismatches are scoring above 50%, lower it.

Click-to-Compare​

Clicking the camera icon on a row that has a match score opens the snapshot modal in side-by-side compare mode — the user's profile photo on the left, the event snapshot on the right, and the match score below. Useful for quick visual confirmation when investigating low-score events or duress alerts.

Advisory, Not Authoritative​

Match scores are recorded for audit and review. They do not grant or deny access — access decisions remain governed entirely by access control rules and credentials. Treat scores as a signal, not a verdict.

Privacy & Compliance​

Some jurisdictions (e.g., Illinois BIPA, EU/UK GDPR Article 9) regulate the collection, use, retention, and disclosure of biometric identifiers. Before enabling system-wide, confirm the feature is lawful in your installation's location and that you have any required consents from individuals whose photos you upload. The Terms of Service includes a dedicated facial recognition section that admins re-acknowledge.

Filtering​

Filter Panel​

Located at top of page:

User Filter:

  • Dropdown of all users with access control
  • Select to show only that user's attempts

Device Filter:

  • Dropdown of all access control devices
  • Select to show only that device/location

Access Type:

  • All Types
  • PIN: PIN code entries only
  • RFID: Card presentations only

Result:

  • All Results
  • Granted: Successful access only
  • Denied: Failed attempts only
  • Forced: Door opened without an authorized unlock in the prior 10 s grace window
  • Held Open: Door stayed open past the rule's held_open_threshold_sec
  • Error: System errors during access attempt

Date Range:

  • From: Start date
  • To: End date

Quick Range:

  • 1D — Last 24 hours
  • 7D — Last 7 days
  • 30D — Last 30 days
  • 90D — Last 90 days
tip

The page accepts a range URL parameter — ?range=today sets From to midnight today, and ?range=1, ?range=7, etc. set the corresponding rolling window. The Dashboard's "access events today" stat links here using ?range=today.

Applying Filters​

Filters apply in real-time as you change selections.

Clear Filters​

Click Clear Filters to reset all filters to defaults.

Result Color Coding​

Access results are color-coded for quick scanning:

  • ✓ Granted (green): Access successfully granted
  • ✕ Denied (red): Access denied
  • Duress (red badge): Granted, but the user entered their duress PIN — the rule's duress macro fired silently. The audit row uses result=granted, reason=duress so the event is easy to find.
  • ⚡ Forced (red pill): Door opened without an authorized unlock in the prior 10 s — inferred from a contact-state transition. Logged but not asserted as ground truth.
  • ⏱ Held Open (amber pill): Door stayed open past the rule's held_open_threshold_sec. The timer re-arms so a propped door keeps reminding rather than going silent.
  • ⚠ Error (orange): System error during access attempt

Access Event Details​

Each log entry includes:

Granted Access​

When access is granted:

  • User identified
  • Credential matched
  • Schedule allowed
  • Action executed (command or macro)
  • Timestamp of access

Denied Access​

When access is denied:

  • User not found
  • Invalid credential
  • Outside schedule (wrong day/hour)
  • Disabled access rule
  • Disabled user account

Denial Reasons:

  • "Invalid PIN"
  • "User not authorized"
  • "Access rule disabled"
  • "Outside schedule hours"
  • "Schedule day not permitted"

Error Events​

System errors during access:

  • Device communication failure
  • Database error
  • Macro execution failure
  • Invalid configuration

Security Monitoring​

Failed Access Attempts​

Monitor for security threats:

Filter:

  • Result: Denied
  • Date: Recent (last 7-30 days)

Red Flags:

  • Multiple denied attempts in short time (brute force)
  • Denied attempts at unusual hours
  • Denied attempts from same device repeatedly
  • Unknown credential attempts

Actions:

  1. Investigate if suspicious
  2. Review access control configuration
  3. Consider temporary disable if attack suspected
  4. Change PINs if compromised
  5. Alert security personnel

Successful Access Auditing​

Track who accessed when:

Filter:

  • Result: Granted
  • User: Specific user (or all)
  • Date Range: Audit period

Audit Uses:

  • Verify employee access times
  • Confirm contractor access during approved hours
  • Compliance reporting
  • Billing (for service access)

Compliance Reporting​

Generating Reports​

  1. Set date range (e.g., last quarter)
  2. Filter by result: Granted
  3. Export data (copy or screenshot)
  4. Format for compliance documentation

Report Includes:

  • All successful access events
  • User identification
  • Location (access device)
  • Timestamp
  • Action taken

Retention Requirements​

Some regulations require access logs:

Common Requirements:

  • Healthcare (HIPAA): 6 years
  • Finance (SOX): 7 years
  • General: 1-3 years

Configure in Data Retention

Deleting Old Logs​

Click Delete Old Logs button:

  1. Prompts for retention period (days)
  2. Enter number of days to keep
  3. Confirms deletion
  4. Deletes all logs older than specified days

Warning: Irreversible deletion. Create backup first if needed.

Use Cases​

Daily Security Review​

Morning security check:

  1. Open Access Log
  2. Filter: Last 24 hours
  3. Review all denied attempts
  4. Investigate anomalies
  5. Verify all granted access is legitimate

User Access Verification​

Confirm guest departed:

  1. Filter by user: guest_user
  2. Check last access timestamp
  3. If recent, guest may still be on-site
  4. If old, safe to disable account

Device Activity Analysis​

Monitor specific entry point:

  1. Filter by device: front_door_keypad
  2. Review access frequency
  3. Identify peak access times
  4. Optimize schedules accordingly

Credential Audit​

Verify user credentials working:

  1. Filter by user
  2. Review their access attempts
  3. Identify pattern of failures (PIN forgotten?)
  4. Assist user or reset PIN

Best Practices​

  1. Regular Review: Check access log daily for security

  2. Investigate Denials: All denied attempts should be explainable

  3. Retention: Keep logs per compliance requirements

  4. Alerts: Configure notifications for failed access attempts

  5. Backup: Export important logs before deletion

  6. Patterns: Look for unusual access patterns

  7. Correlation: Use the snapshot button to review camera images from access events

Troubleshooting​

No Logs Appearing​

Check:

  1. Access control rules configured
  2. Access control rules enabled
  3. Users have PINs/RFID configured
  4. Access device online and working
  5. Date range includes expected events

Cannot Filter​

Check:

  1. Logs exist for filter criteria
  2. Date range set correctly
  3. Filters not too restrictive (no matches)

Cannot Delete Logs​

Check:

  1. Database permissions
  2. Logs not locked by another process
  3. Sufficient time for deletion (large delete may take time)