Skip to main content

Kisi Access Control Module

The Kisi module on Aida Controller connects Kisi door access to building automation: unlock and lock events can drive lights, shades, and room scenes, and Kisi locks appear as first-class access_control devices you can unlock, lock down, schedule, and use as event-redirection targets.

:::info Version requirement Kisi requires Aida Controller 2.0 v0.95.0 or later, and an Aida Platform site with the Kisi relay enabled (platform v0.41.0+). The controller must be paired to the site (cloud MQTT / contract ID). :::

:::note Where operators work Configure actors, locks, scene rules, and door control on the controller (Modules → Kisi). Aida Platform is a thin relay: organization webhook URL, optional shared secret, and Place → controller bindings. It does not host Actors / Actions / Event Log UI. :::

Overview​

This module provides:

  • Access event → scene automation — when a known person unlocks (or locks) a door, run dim / CCT / RGBW / shade outputs on clusters, zones, or devices
  • Locks as devices — Kisi locks in inventory with online / unlocked / open / lockdown state
  • Door control — unlock, lockdown, and cancel lockdown from Control and device detail (edge calls to Kisi Cloud with your API key)
  • Place binding — saving a Kisi Place ID on the controller registers that Place with the platform over MQTT so webhooks route to this appliance
  • Event log — recent access and door events for commissioning and troubleshooting
  • Schedules & redirections — Kisi locks in device-schedule CSV (node type Kisi) and as allow-listed redirection targets

How it works​

HopRole
Kisi organization webhookSends access/door events to Aida Platform
PlatformAuthenticates webhook, looks up Place → controller, publishes MQTT
Controller kisi moduleIngests events, matches scene rules, polls lock state, unlocks via Kisi API
Place bindController publishes {action:bind, placeId, placeName?} on MQTT when you Save Setup

Production webhook host:

https://api.aida-platform.com/api/kisi/webhook

Platform Sites → Kisi may append ?siteId=… for site-scoped secret isolation. Routing to a controller is by Kisi Place ID, not by the query string alone.

Prerequisites​

Before enabling Kisi, ensure you have:

  • Aida Controller 2.0 paired to the site (MQTT connected)
  • Kisi organization admin access (webhooks + Place / lock IDs)
  • Kisi Place ID for the building (and optionally a friendly Place name for the platform bindings table)
  • Kisi API key (login/API key) on the controller for Discover, poll, unlock, and lockdown
  • Operator access to enable modules on the controller and open Sites → Kisi on the platform
  • Commissioned clusters / zones / devices if you want unlock events to drive lighting or shades

Setup process​

Step 1: Enable the platform relay​

  1. In Aida Platform, open the site and go to Sites → Kisi (integration dialog).
  2. Enable the Kisi relay for the site.
  3. Copy the webhook URL and configure or rotate the shared secret if you use one.
  4. Leave the bindings table open — after the controller Saves Place, a row should appear for that Place ID.

Step 2: Point Kisi at Aida​

  1. In Kisi admin, open organization Webhooks.
  2. Add a webhook aimed at the URL from Step 1 (HTTPS in production).
  3. If you set a shared secret in Kisi, configure the same secret on the platform Kisi dialog.

Step 3: Enable the controller module​

  1. Open the controller UI → Modules.
  2. Enable Kisi (kisi).
  3. Open Modules → Kisi. Confirm the header shows MQTT connected when the platform link is healthy.

Step 4: Bind Place and API key (Setup)​

On the Setup tab:

  1. Copy the Webhook URL shown on Setup if you still need it for Kisi org settings (same family of URL as the platform dialog).
  2. Enter Place ID (required) — the Kisi Place for this controller.
  3. Optionally enter Place name — a friendly label shown on the platform bindings table (avoids opaque or leftover debug names).
  4. Paste the Kisi API key used for edge unlock and poll.
  5. Set Poll interval (seconds; typically 60).
  6. Click Save.

Saving publishes MQTT Place bind. The platform should list the binding; Setup may refresh the webhook URL from bind_ack.

:::tip One Place per controller (typical) Bind the Place that should deliver events to this appliance. A Place can only be active on one controller at a time; binding elsewhere conflicts until unbound. :::

Step 5: Actors​

On the Actors tab, add people who should drive scene rules:

  • Name — display label
  • Email — must match the actor email on Kisi unlock webhooks

Scene matching keys off this email (case-normalized), not the display name.

Step 6: Locks​

On the Locks tab:

  1. Click Discover locks (requires a valid API key and Place) or
  2. Add a lock manually with name + Kisi Lock ID.

Adopted locks become KISI / access_control devices in inventory (assign a cluster when you use schedules or facility context).

Step 7: Scene rules (Actions)​

On the Actions tab, create rules:

FieldMeaning
ActorEmail from the Actors list
LockLock ID from the Locks list
Access actionTypically unlock or locked
OutputsDim, RGBW, CCT, and/or shade
TargetsClusters, zones, and/or devices

Use Test on a rule to simulate an event without walking to the door. Successful scenes pause Solaris / Circadian on affected targets the same way other manual/automation sources do.

Step 8: Verify the Log​

On the Log tab, filter by actor, device, or action. After a real unlock (or a simulated rule), you should see ingest entries. If the log stays empty while Kisi shows activity, revisit Place bind and webhook routing (below).

Day-to-day use​

Unlock and lockdown​

From Control or a Kisi device detail page:

  • Unlock — momentary cloud unlock (door re-secures per Kisi configuration)
  • Lockdown — deny access until cancelled
  • Cancel lockdown — clear lockdown

These call Kisi Cloud from the controller using the module API key. There is no separate “lock now” command; use lockdown or wait for auto-relock.

Device schedule​

Device schedule CSV supports node type Kisi with serial = lock ID. Import creates or updates lock devices; discovery merges on the same id. Keep the API key in module Setup — not in the CSV.

Event redirections​

Event redirections may target Kisi locks with unlock, lockdown, or cancel_lockdown only. Prefer kisi Actions for rules that depend on a specific person’s email; use redirections for lock- or cluster-scoped automation without an actor.

Using the module when disabled​

When Kisi is disabled under Modules:

  • MQTT ingest and poll stop
  • Unlock / lockdown APIs are rejected
  • Scene rules do not run
  • Existing devices remain visible but state goes stale

Turn the module back on to resume.

Troubleshooting​

SymptomWhat to check
No events on LogPlatform relay enabled; Kisi webhook URL correct; Place ID Saved (binding row on platform); controller MQTT connected
Events on platform but not controllerBinding contractId matches this controller; module Enabled
Discover / unlock failsAPI key valid; Place ID correct; outbound HTTPS to api.kisi.io
Scene does not fireActor email matches webhook; lock ID matches; access action (unlock / locked); targets commissioned
Wrong Place name on platformSet Place name on Setup and Save (empty name clears a stale label)
Place already bound elsewhereUnbind on the other controller or clear Place there, then Save here

Support​

For support, contact your system administrator or MHT Technologies.