From fa4b54257d3e7650f50771865cd01bab1824dd02 Mon Sep 17 00:00:00 2001 From: dawnho Date: Thu, 9 Jul 2026 14:15:30 -0700 Subject: [PATCH] feat: add Kisi locks brand guide Documents the Phase 1 Kisi integration (cloud access control) whose doors appear as `kisi_lock` devices supporting remote unlock. Includes overview, setup guide, 5-step getting-started tutorial in all 7 SDK languages, and sandbox credentials, plus a clearly-labeled Planned Capabilities section for cloud keys, access grants, mobile keys, and cards. - Adds overview, setup guide, getting-started, and sandbox pages under device-and-system-integration-guides/kisi-locks/ - Updates docs.json nav, brand-guides index card, and SUMMARY.mdx Co-Authored-By: Claude Opus 4.8 --- .../SUMMARY.mdx | 4 + .../index.mdx | 4 + .../get-started-with-kisi-locks.mdx | 439 ++++++++++++++++++ .../kisi-locks/index.mdx | 78 ++++ .../kisi-locks/kisi-setup-guide.mdx | 61 +++ .../kisi-locks/sandbox-kisi-locks.mdx | 14 + mintlify-docs/docs.json | 9 + 7 files changed, 609 insertions(+) create mode 100644 mintlify-docs/device-and-system-integration-guides/kisi-locks/get-started-with-kisi-locks.mdx create mode 100644 mintlify-docs/device-and-system-integration-guides/kisi-locks/index.mdx create mode 100644 mintlify-docs/device-and-system-integration-guides/kisi-locks/kisi-setup-guide.mdx create mode 100644 mintlify-docs/device-and-system-integration-guides/kisi-locks/sandbox-kisi-locks.mdx diff --git a/mintlify-docs/device-and-system-integration-guides/SUMMARY.mdx b/mintlify-docs/device-and-system-integration-guides/SUMMARY.mdx index ac431816e..3e86c4645 100644 --- a/mintlify-docs/device-and-system-integration-guides/SUMMARY.mdx +++ b/mintlify-docs/device-and-system-integration-guides/SUMMARY.mdx @@ -123,6 +123,10 @@ title: 'Brand Guides' - [Keynest Key Lockers](/device-and-system-integration-guides/keynest-key-lockers/index) - [Keynest Setup Instructions](/device-and-system-integration-guides/keynest-key-lockers/keynest-setup-instructions) - [Sandbox Keynest Lockers](/device-and-system-integration-guides/keynest-key-lockers/sandbox-keynest-lockers) +- [Kisi Locks](/device-and-system-integration-guides/kisi-locks/index) + - [Kisi Setup Guide](/device-and-system-integration-guides/kisi-locks/kisi-setup-guide) + - [Get Started with Kisi Locks](/device-and-system-integration-guides/kisi-locks/get-started-with-kisi-locks) + - [Sandbox Kisi Locks](/device-and-system-integration-guides/kisi-locks/sandbox-kisi-locks) - [Kwikset Locks](/device-and-system-integration-guides/kwikset-locks/index) - [Get started with Kwikset Wi-Fi Locks](/device-and-system-integration-guides/kwikset-locks/get-started-with-kwikset-wifi-locks) - [Sandbox Kwikset Locks](/device-and-system-integration-guides/kwikset-locks/kwikset-locks-sample-data) diff --git a/mintlify-docs/device-and-system-integration-guides/index.mdx b/mintlify-docs/device-and-system-integration-guides/index.mdx index 52407dc19..11b2d5f0f 100644 --- a/mintlify-docs/device-and-system-integration-guides/index.mdx +++ b/mintlify-docs/device-and-system-integration-guides/index.mdx @@ -63,6 +63,10 @@ To find the integration guide for each of your devices or systems, see the follo title='KeyInCode Locks' href='/device-and-system-integration-guides/keyincode-locks' > + + +```bash JavaScript +npm i seam +``` + +```bash Python +pip install seam +# For some development environments, use pip3 in this command instead of pip. +``` + +```bash Ruby +bundle add seam +``` + +```bash PHP +composer require seamapi/seam +``` + +```bash C# +Install using nuget: https://www.nuget.org/packages/Seam +``` + +```bash Java +// Add to your pom.xml or build.gradle — see Maven Central for details. +``` + +```bash cURL (bash) +# cURL is already installed on most systems. No additional installation needed. +# Export your API key as an environment variable: +export SEAM_API_KEY=seam_test2ZTo_0mEYQW2TvNDCxG5Atpj85Ffw +``` + + + +Once installed, [sign up for Seam](https://console.seam.co/) to get your API key, and export it as an environment variable: + +```bash +export SEAM_API_KEY=seam_test2ZTo_0mEYQW2TvNDCxG5Atpj85Ffw +``` + + + This guide uses a Sandbox Workspace. Only virtual devices can be connected. If + you need to connect a real Kisi organization, use a non-sandbox workspace and + API key. + + +--- + +## 2 — Link Kisi Account with Seam + +To control your Kisi locks via the Seam API, you must first authorize your Seam workspace against your Kisi organization. To do so, Seam provides [Connect Webviews](/core-concepts/connect-webviews): pre-built UX flows that walk your users through authorizing your application to control their Kisi locks. + +Kisi connects using a **Kisi API key**. In production, your users generate this key in their Kisi dashboard under **My Account → API**. See the [Kisi Setup Guide](./kisi-setup-guide) for details. + +#### Request a Connect Webview + + + +```javascript JavaScript +import { Seam } from "seam"; + +const seam = new Seam(); + +const connectWebview = await seam.connectWebviews.create({ + accepted_providers: ["kisi"], +}); + +console.log(connectWebview.login_successful); // false + +// Send the webview URL to your user +console.log(connectWebview.url); +``` + +```python Python +from seam import Seam + +seam = Seam() + +webview = seam.connect_webviews.create(accepted_providers=["kisi"]) + +assert webview.login_successful is False + +# Send the webview URL to your user +print(webview.url) +``` + +```ruby Ruby +require "seam" + +seam = Seam.new(api_key: "MY_API_KEY") + +webview = seam.connect_webviews.create( + accepted_providers: ["kisi"] +) + +puts webview.login_successful # false + +# Send the webview URL to your user +puts webview.url +``` + +```php PHP +connect_webviews->create( + accepted_providers: ["kisi"] +); + +echo $webview->login_successful; // false + +// Send the webview URL to your user +echo $webview->url; +``` + +```csharp C# +using Seam.Client; + +var seam = new SeamClient(apiToken: "YOUR_API_KEY"); + +var webview = seam.ConnectWebviews.Create( + acceptedProviders: new List { "kisi" } +); + +Console.WriteLine(webview.LoginSuccessful); // false + +// Send the webview URL to your user +Console.WriteLine(webview.Url); +``` + +```java Java +import co.seam.Seam; +import co.seam.api.types.ConnectWebview; + +Seam seam = Seam.builder().apiKey("YOUR_API_KEY").build(); + +ConnectWebview webview = seam.connectWebviews().create( + ConnectWebviewsCreateRequest.builder() + .acceptedProviders(List.of("kisi")) + .build() +); + +System.out.println(webview.getLoginSuccessful()); // false + +// Send the webview URL to your user +System.out.println(webview.getUrl()); +``` + +```bash cURL (bash) +curl -X 'POST' \ + 'https://connect.getseam.com/connect_webviews/create' \ + -H "Authorization: Bearer ${SEAM_API_KEY}" \ + -H 'Content-Type: application/json' \ + -d '{ + "accepted_providers": ["kisi"] + }' +``` + + + +#### Authorize Your Workspace + +Navigate to the URL returned by the Webview object. Since you are using a sandbox workspace, complete the login flow by entering the Kisi [sandbox test account](/device-and-system-integration-guides/kisi-locks/sandbox-kisi-locks) API key below: + +- **API Key:** `fake_kisi_api_key` + +Confirm the Connect Webview was successful by querying its status: + + + +```javascript JavaScript +const updatedWebview = await seam.connectWebviews.get( + connectWebview.connect_webview_id +); + +console.log(updatedWebview.login_successful); // true +``` + +```python Python +updated_webview = seam.connect_webviews.get( + connect_webview_id=webview.connect_webview_id +) + +assert updated_webview.login_successful # true +``` + +```ruby Ruby +updated_webview = seam.connect_webviews.get( + connect_webview_id: webview.connect_webview_id +) + +puts updated_webview.login_successful # true +``` + +```php PHP +connect_webviews->get( + connect_webview_id: $webview->connect_webview_id +); + +echo $updated_webview->login_successful; // true +``` + +```csharp C# +var updatedWebview = seam.ConnectWebviews.Get( + connectWebviewId: webview.ConnectWebviewId +); + +Console.WriteLine(updatedWebview.LoginSuccessful); // true +``` + +```java Java +ConnectWebview updatedWebview = seam.connectWebviews().get( + ConnectWebviewsGetRequest.builder() + .connectWebviewId(webview.getConnectWebviewId()) + .build() +); + +System.out.println(updatedWebview.getLoginSuccessful()); // true +``` + +```bash cURL (bash) +curl -X 'POST' \ + 'https://connect.getseam.com/connect_webviews/get' \ + -H "Authorization: Bearer ${SEAM_API_KEY}" \ + -H 'Content-Type: application/json' \ + -d "{ + \"connect_webview_id\": \"${CONNECT_WEBVIEW_ID}\" + }" +``` + + + +--- + +## 3 — Retrieve Kisi Lock Devices + +After a Kisi account is linked with Seam, you can retrieve the locks for that Kisi organization. The Seam API exposes each lock's properties, including its online status and Kisi-specific metadata such as the lock's place. + + + +```javascript JavaScript +const allLocks = await seam.locks.list(); + +const someLock = allLocks[0]; + +console.log(someLock.properties.online); // true + +console.log(someLock); +/* +{ + device_id: '...', + device_type: 'kisi_lock', + capabilities_supported: ['lock'], + properties: { + online: true, + manufacturer: 'kisi', + kisi_metadata: { + lock_id: 100, + lock_name: 'Front Door', + place_name: 'Main Office', + description: 'Electric strike at main entrance' + }, + name: 'Front Door' + }, + ... +} +*/ +``` + +```python Python +all_locks = seam.locks.list() + +some_lock = all_locks[0] + +assert some_lock.properties["online"] is True + +print(some_lock) +# Device( +# device_id='...', +# device_type='kisi_lock', +# properties={ +# 'online': True, +# 'manufacturer': 'kisi', +# 'kisi_metadata': { +# 'lock_id': 100, +# 'lock_name': 'Front Door', +# 'place_name': 'Main Office', +# 'description': 'Electric strike at main entrance' +# }, +# 'name': 'Front Door' +# }, +# capabilities_supported=['lock'] +# ) +``` + +```ruby Ruby +some_lock = seam.locks.list.first + +puts some_lock.properties.online # true + +puts some_lock +``` + +```php PHP +locks->list(); + +$some_lock = $locks[0]; + +echo $some_lock->properties->online; // true +``` + +```csharp C# +var locks = seam.Locks.List(); + +var someLock = locks[0]; + +Console.WriteLine(someLock.Properties.Online); // true +``` + +```java Java +var locks = seam.locks().list(); + +var someLock = locks.get(0); + +System.out.println(someLock.getProperties().getOnline()); // true +``` + +```bash cURL (bash) +curl -X 'POST' \ + 'https://connect.getseam.com/locks/list' \ + -H "Authorization: Bearer ${SEAM_API_KEY}" \ + -H 'Content-Type: application/json' \ + -d '{}' +``` + + + +--- + +## 4 — Unlocking a Door + +You can trigger a remote unlock on a Kisi lock. Kisi processes the unlock through its cloud, so the action is fire-and-forget — Seam does not receive a confirmation of the physical unlock from the device. + + + Kisi does not support a remote lock action. Only unlock is available. Unlock + requests against locks with geofence or reader-proximity restrictions may be + rejected by Kisi. + + + + +```javascript JavaScript +// unlock the door +await seam.locks.unlockDoor(someLock.device_id); +``` + +```python Python +# unlock the door +seam.locks.unlock_door(device_id=some_lock.device_id) +``` + +```ruby Ruby +# unlock the door +seam.locks.unlock_door(device_id: some_lock.device_id) +``` + +```php PHP +locks->unlock_door(device_id: $some_lock->device_id); +``` + +```csharp C# +// unlock the door +seam.Locks.UnlockDoor(deviceId: someLock.DeviceId); +``` + +```java Java +// unlock the door +seam.locks().unlockDoor(LocksUnlockDoorRequest.builder() + .deviceId(someLock.getDeviceId()) + .build()); +``` + +```bash cURL (bash) +# unlock the door +curl -X 'POST' \ + 'https://connect.getseam.com/locks/unlock_door' \ + -H "Authorization: Bearer ${SEAM_API_KEY}" \ + -H 'Content-Type: application/json' \ + -d "{\"device_id\": \"${DEVICE_ID}\"}" +``` + + + +--- + +## Next Steps + +Now that you've completed this guide, you can try to connect a real Kisi organization. To do so, make sure to switch to a non-sandbox workspace and API key as real devices cannot be connected to sandbox workspaces. + +In addition, if you'd like to explore other aspects of Seam, here is a list of helpful resources: + +- [Receiving webhooks](/developer-tools/webhooks) for [device events](/api/events/list) +- [Core Concepts](/core-concepts/overview) +- [Locking and Unlocking](/low-level-apis/smart-locks/lock-and-unlock) + +If you have any questions or want to report an issue, email us at [support@seam.co](mailto:support@seam.co). diff --git a/mintlify-docs/device-and-system-integration-guides/kisi-locks/index.mdx b/mintlify-docs/device-and-system-integration-guides/kisi-locks/index.mdx new file mode 100644 index 000000000..64febbc17 --- /dev/null +++ b/mintlify-docs/device-and-system-integration-guides/kisi-locks/index.mdx @@ -0,0 +1,78 @@ +--- +title: 'Kisi Locks' +sidebarTitle: 'Overview' +description: 'Guide for using Kisi cloud access control with Seam' +--- + +## Overview + +Kisi is a cloud-based access control provider. Kisi controllers and readers are installed on doors, and members unlock those doors with mobile credentials, key cards, or from the Kisi dashboard. Access is managed centrally in a Kisi organization, which is organized into places (sites) and locks (doors). + +Seam integrates with Kisi to trigger remote unlock actions on the doors in your Kisi organization. Because Kisi is cloud-native, no additional Seam gateway or bridge is required — Seam communicates with your locks through the Kisi cloud. + + + Seam authorizes against your Kisi organization using a Kisi API key. There is no separate Seam hardware to install. Your Kisi controllers must be online for remote unlock to succeed. + + +--- + +## Supported Devices + +This integration supports the locks (doors) in your Kisi organization that are managed through Kisi controllers. Each Kisi lock appears in Seam as a device with the `kisi_lock` device type. + + + Kisi has no remote re-lock endpoint, so Seam supports remote **unlock** only — there is no lock action. Kisi readers also have no keypads, so PIN-based access codes are not available. + + +For detailed information about the Kisi devices that Seam supports, see our [Kisi Supported Devices page](https://www.seam.co/manufacturers/kisi). + +--- + +## Supported Features + +We support the following features: + +- [Triggering remote unlock actions](/low-level-apis/smart-locks/lock-and-unlock) + +--- + +## Planned Capabilities + +Seam's Kisi integration is expanding. The following capabilities are on the roadmap and are **not yet available**: + + + These features are planned and not currently usable. The sections below describe where Seam is headed with Kisi, not what you can build today. + + +- **User-attributed unlock (cloud keys)** — Unlock doors on behalf of a specific Kisi user so the action is attributed to that person in Kisi's audit log. +- **[Access Grants](/use-cases/granting-access)** — Provision Kisi users, groups, and time-bound access to specific doors. +- **Mobile keys** — Issue Kisi app credentials for in-app, BLE, and NFC unlock. +- **Key cards** — Manage physical card credentials. + +--- + +## Brand-Specific Restrictions + +- **Unlock only.** Kisi does not expose a remote re-lock action, so Seam supports unlock but not lock. +- **No access codes.** Kisi readers do not have keypads, so PIN-based access codes are not supported. +- **Restricted locks may reject unlocks.** Locks configured in Kisi with geofence or reader-proximity restrictions may reject remote API unlocks. Seam surfaces a warning on these devices. + +--- + +## Device Provider Key + +To create a [Connect Webview](/core-concepts/connect-webviews) that enables your users to connect their Kisi devices to Seam, include the `kisi` device provider key in the `accepted_providers` list. For more information, see [Customize the Brands to Display in Your Connect Webviews](/core-concepts/connect-webviews/customizing-connect-webviews#customize-the-brands-to-display-in-your-connect-webviews). + +--- + +## Setup Instructions + +For step-by-step instructions on connecting Kisi devices to Seam — including how to generate a Kisi API key and troubleshooting — see the [Kisi Setup Guide](./kisi-setup-guide). + +--- + +## Where to Order + + + + diff --git a/mintlify-docs/device-and-system-integration-guides/kisi-locks/kisi-setup-guide.mdx b/mintlify-docs/device-and-system-integration-guides/kisi-locks/kisi-setup-guide.mdx new file mode 100644 index 000000000..18b5fc2e2 --- /dev/null +++ b/mintlify-docs/device-and-system-integration-guides/kisi-locks/kisi-setup-guide.mdx @@ -0,0 +1,61 @@ +--- +title: 'Kisi Setup Guide' +description: 'Connect your Kisi organization to Seam using a Kisi API key.' +--- + +## Overview + +This guide walks you through connecting your Kisi organization to Seam. Seam authorizes against Kisi using an API key that you generate in the Kisi dashboard. Your Kisi controllers and locks must already be set up and online in Kisi before you begin. + +--- + +## Step 1: Generate a Kisi API Key + +Seam connects to Kisi with an API key rather than a login email and password. + +To generate a key: + +1. Sign in to the [Kisi dashboard](https://web.kisi.io/). +2. Go to **My Account → API**. +3. Create a new API key and copy it. + +For detailed instructions, see Kisi's guide on [generating an API key](https://docs.kisi.io/dashboard/account/generate_api_key/). + + + Generate the API key from an account that is an **organization owner**, so Seam has permission to see and unlock all of the locks you want to manage. A key inherits the permissions of the user who created it. + + +--- + +## Step 2: Connect to Seam via Connect Webview + +1. Open the [Connect Webview](/core-concepts/connect-webviews) provided by your application. +2. Select Kisi as the provider. +3. Paste your Kisi **API key** into the field and submit. +4. Once authorized, the locks in your Kisi organization appear as devices in Seam. + +--- + +## Step 3: Verify the Connection + +After connecting, verify that your Kisi locks appear as devices and show as online with unlock capability. Locks that have geofence or reader-proximity restrictions enabled in Kisi display a warning, because remote unlocks against those locks may be rejected. + +--- + +## Troubleshooting + +### Authorization fails in Connect Webview + +Confirm that you pasted a valid, active Kisi API key. Keys created in the Kisi dashboard can expire after a period of inactivity — if authorization fails, generate a fresh key and try again. Make sure the key belongs to an organization owner so it can access your locks. + +### Locks not appearing after authorization + +Ensure the locks exist in your Kisi organization and are assigned to a place. Seam lists the locks that the API key's user can access, so a key from a user with limited permissions may not see every lock. + +### Lock shows as offline + +Check that the Kisi controller for that door is powered on and connected to the network. Seam can only unlock locks whose controllers are online. + +### Unlock is rejected + +If a lock has geofence or reader-proximity restrictions enabled in Kisi, remote API unlocks may be denied. Review the lock's restriction settings in the Kisi dashboard. diff --git a/mintlify-docs/device-and-system-integration-guides/kisi-locks/sandbox-kisi-locks.mdx b/mintlify-docs/device-and-system-integration-guides/kisi-locks/sandbox-kisi-locks.mdx new file mode 100644 index 000000000..b0aeaca74 --- /dev/null +++ b/mintlify-docs/device-and-system-integration-guides/kisi-locks/sandbox-kisi-locks.mdx @@ -0,0 +1,14 @@ +--- +title: 'Sandbox Kisi Locks' +description: 'Add virtual Kisi locks to your Seam sandbox workspace using this sample API key to test your integration without real hardware.' +--- + +Use the following API key to add virtual [Kisi locks](/device-and-system-integration-guides/kisi-locks) to your Seam [sandbox workspace](/core-concepts/workspaces#sandbox-workspaces): + +| API Key | +| ----------------- | +| `fake_kisi_api_key` | + +Kisi connects using a single API key rather than a login email and password. When you open the Connect Webview in a sandbox workspace, select Kisi and paste the API key above. + +The sandbox organization includes two virtual locks — **Front Door** (online) and **Back Door** (offline, with restrictions enabled) — in a place named **Main Office**. Use these to test retrieving devices and triggering remote unlock actions. diff --git a/mintlify-docs/docs.json b/mintlify-docs/docs.json index ab93a41ee..e6704e0a1 100644 --- a/mintlify-docs/docs.json +++ b/mintlify-docs/docs.json @@ -1043,6 +1043,15 @@ "device-and-system-integration-guides/keyincode-locks/sandbox-keyincode-locks" ] }, + { + "group": "Kisi Locks", + "pages": [ + "device-and-system-integration-guides/kisi-locks/index", + "device-and-system-integration-guides/kisi-locks/kisi-setup-guide", + "device-and-system-integration-guides/kisi-locks/get-started-with-kisi-locks", + "device-and-system-integration-guides/kisi-locks/sandbox-kisi-locks" + ] + }, { "group": "Kwikset Locks", "pages": [