Connect Lenel OnGuard to KODE OS for access control data integration
Overview
Use this integration to connect your Lenel OnGuard (8.3+) system to KODE OS. You receive real-time access, credential, and alarm activity over SignalR (WebSocket) while REST covers historical polling and inventory-style data such as badges and alarm definitions.Supported Capabilities
- Collect Non-Sensor Data (Access Events, Alarms, Credentials)
- Receive Real-Time Events via SignalR (WebSocket)
- Collect Historical Data via REST
Prerequisites
- OnGuard 8.3 system with OpenAccess API enabled
- Valid username and password credentials for the OnGuard system
- A
LENEL_API_KEY(Application ID) configured as an environment variable in the KODE OS API Integration Service — this key is shared across all Lenel datasources - Network connectivity from KODE OS to the OnGuard server (both REST and WebSocket endpoints)
- KODE OS environment with access to Data Sources
Configure Connector in KODE OS
- Navigate to Data Sources in your building
- Click API Catalog and search for OnGuard
- Click + Add Datasource
- Fill in the fields below and complete the three-page setup flow
How Authentication Works
OnGuard uses a session-based authentication flow:- KODE OS sends credentials to
POST /api/access/onguard/openaccess/authenticationwith theApplication-Idheader - OnGuard returns a
session_tokenand APIversion - All subsequent requests include
Session-TokenandApplication-Idheaders
If authentication fails due to invalid credentials, expired password, or invalid application ID, the connector automatically deactivates to prevent account lockout. Check the connector status page if data stops flowing.
Data Collection Methods
OnGuard data is collected through two channels:What Data You Get
Access Logs
Real-time access events from card readers, doors, and entry points, delivered via SignalR WebSocket.Alarms
Alarm definitions collected via REST polling, providing the alarm inventory for the site.Access Cards
Badge and credential inventory collected daily via REST as a backup to real-time SignalR software events.Event Logs
Alarm acknowledgment events collected via SignalR in real time.Polling Schedule
- Access Log — Real-time via SignalR; REST backup every 1 hour (min: 1 hour, max: 24 hours)
- Access Card — Daily REST poll (badge inventory backup)
- Alarm — REST poll every 1 hour (alarm definitions)
- Event Log — Real-time via SignalR
Use Cases
Once connected, this integration enables you to:- Receive real-time door access events (granted/denied) across all entry points for live security monitoring
- Track credential lifecycle: activations, deactivations, and badge type classifications
- Centralize alarm management with priority levels, instruction text, and acknowledgment audit trails
- Correlate access patterns with occupancy and energy data for building optimization
- Generate compliance reports with detailed audit trails for every access event
Troubleshooting
WebSocket/SignalR connection failed
WebSocket/SignalR connection failed
Verify the URL and credentials are correct. Ensure the OnGuard OpenAccess API is enabled and the
LENEL_API_KEY environment variable is set correctly. Check that network firewalls allow WebSocket connections from the KODE OS server to the OnGuard host.Connector auto-deactivated
Connector auto-deactivated
The connector automatically deactivates on authentication failures to prevent account lockout. Common causes: expired password, invalid Application ID, or locked account. Fix the credentials and re-enable the connector from the Data Sources page.
Data collection stops or gaps appear
Data collection stops or gaps appear
Check the connector status on the Data Sources page. For SignalR data, verify the WebSocket connection is active. For REST data (badges, alarms), check that the OnGuard server is reachable and responding. Review error logs on the connector detail page.