Overview

Maptician leverages Brivo’s external Application Management feature to access Brivo’s API, subscribing to access control system events. These events are relayed to Maptician via webhook, informing the Maptician system about users’ presence status and location details.

Integration Requirements

• Brivo-provided API Key.
• Client ID and Client Secret, are obtained through the external application registration process in the Brivo Access App.
• Brivo Access account with credentials (username and password) having adequate permissions (must be a “super admin” account) to access location and employee data and subscribe to webhook events.

Credential Management & Authentication

• Maptician users with Account Administrator access can input the required keys, IDs, and passwords in Maptician’s user interface. These fields are located under “Settings” (upper right in Maptician’s desktop web app), within the “Presence” section under the left navigation menu, specifically in the “Brivo Integration” subsection.
• All entered values are securely stored in AWS Secrets Manager for subsequent retrieval within the application.
• Maptician employs the ‘password’ grant type within Brivo’s custom app integrations, using provided user and client credentials to obtain access and refresh tokens from Brivo’s API. These tokens are cached on Maptician’s servers for API request authentication and are refreshed before expiration. TLS 1.2 or higher secures all connections to the Brivo API.

Data Integrations

• Maptician’s integration aims to convert Brivo building access events into Maptician presence data, identifying the individual and the accessed facility.
• Access events from Brivo include ID values for individuals and locations but typically lack direct identifiers (like email or location name). Therefore, Maptician creates and maintains mappings of Brivo User IDs with Maptician user-profiles and Brivo Site IDs with Maptician locations.
• The Maptician/Brivo integration comprises four primary interfaces:
  • Daily sync of User IDs between Brivo and Maptician.
  • Daily sync of Site IDs between Brivo and Maptician locations.
  • Webhook subscription for Brivo access events.
  • Maptician-managed endpoint for receiving and processing Brivo access events.

Brivo > Maptician User ID Sync

• Maptician synchronizes with Brivo’s user list (accessible at Brivo User API Endpoint) daily at 4:40 AM Eastern Time.
• It compares Brivo IDs with Maptician's database. Unmatched Brivo profiles are disregarded for sync purposes, while matched ones are cached in Maptician.

Brivo > Maptician Location ID Sync

• Similar to user ID sync, Maptician syncs site data from Brivo (Brivo Site API Endpoint) at the same daily schedule.
• Maptician compares Brivo site names with its location names. Maptician's IT team can set an internal ‘brivo_name’ value for unmatched site names, facilitating case-insensitive but exact matching.

Brivo Event Subscriptions

• Maptician subscribes to Brivo access control events at the Brivo Event Subscription API Endpoint, focusing on “open” action types, which indicate single access events.
• On disabling the integration via Maptician’s settings, these subscriptions are canceled.

Event Webhook Endpoint

• Maptician maintains a unique webhook endpoint for each tenant: https://{subdomain}.maptician.com/ext/inbound/brivo/webhooks/entry_event
• The endpoint processes events with a “securityAction” type of “Open”, utilizing the “id” properties from the event payload to match Maptician users and locations based on established syncs.
• Presence status for identified users is set to the corresponding location for the day, unaffected by subsequent entries.