Get Started with the Kisi Access Control System

Overview

Seam provides a universal API to connect and control many brands of access control systems. This guide provides a rapid introduction to connecting your Kisi organization, granting a cloud key, and remotely unlocking a door using the Seam API. Kisi is cloud-native, so no Seam gateway or bridge is required. Seam models each Kisi organization as an access control system, exposes each door as an entrance, and issues cloud keys through Access Grants. To learn more about other access control systems supported by Seam, head over to our integration page.

1 — Install Seam SDK

Seam provides client libraries for many languages, such as JavaScript, Python, Ruby, PHP, and others, as well as a Postman collection and OpenAPI spec.

JavaScript / TypeScript (npm, GitHub)
Python (pip, GitHub)
Ruby Gem (rubygem, GitHub)
PHP (packagist, GitHub)
C# (nuget, GitHub)
Java (Maven, GitHub)

npm i seam

pip install seam
# For some development environments, use pip3 in this command instead of pip.

bundle add seam

composer require seamapi/seam

Install using nuget: https://www.nuget.org/packages/Seam

// Add to your pom.xml or build.gradle — see Maven Central for details.

# 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 to get your API key, and export it as an environment variable:

export SEAM_API_KEY=seam_test2ZTo_0mEYQW2TvNDCxG5Atpj85Ffw

This guide uses a Sandbox Workspace. Only virtual systems can be connected. If you need to connect a real Kisi organization, use a non-sandbox workspace and API key.

2 — Link Kisi System with Seam

To control your Kisi system via the Seam API, you must first authorize your Seam workspace against your Kisi organization. To do so, Seam provides Connect Webviews: pre-built UX flows that walk your users through authorizing your application to control their Kisi system. 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 for details.

Request a Connect Webview

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)

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)

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
use Seam\SeamClient;

$seam = new SeamClient("YOUR_API_KEY");

$webview = $seam->connect_webviews->create(
  accepted_providers: ["kisi"]
);

echo $webview->login_successful; // false

// Send the webview URL to your user
echo $webview->url;

using Seam.Client;

var seam = new SeamClient(apiToken: "YOUR_API_KEY");

var webview = seam.ConnectWebviews.Create(
  acceptedProviders: new List<string> { "kisi" }
);

Console.WriteLine(webview.LoginSuccessful); // false

// Send the webview URL to your user
Console.WriteLine(webview.Url);

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());

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 API key below:

API Key: 1234

Confirm the Connect Webview was successful by querying its status:

const updatedWebview = await seam.connectWebviews.get(
  connectWebview.connect_webview_id,
)

console.log(updatedWebview.login_successful) // true

updated_webview = seam.connect_webviews.get(
    connect_webview_id=webview.connect_webview_id
)

assert updated_webview.login_successful  # true

updated_webview = seam.connect_webviews.get(
  connect_webview_id: webview.connect_webview_id
)

puts updated_webview.login_successful # true

<?php
$updated_webview = $seam->connect_webviews->get(
  connect_webview_id: $webview->connect_webview_id
);

echo $updated_webview->login_successful; // true

var updatedWebview = seam.ConnectWebviews.Get(
  connectWebviewId: webview.ConnectWebviewId
);

Console.WriteLine(updatedWebview.LoginSuccessful); // true

ConnectWebview updatedWebview = seam.connectWebviews().get(
  ConnectWebviewsGetRequest.builder()
    .connectWebviewId(webview.getConnectWebviewId())
    .build()
);

System.out.println(updatedWebview.getLoginSuccessful()); // true

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 the ACS System

After the Kisi system is linked with Seam, you can retrieve the ACS system. This represents the connected Kisi organization.

const systems = await seam.acs.systems.list()

const kisiSystem = systems[0]

console.log(kisiSystem)
/*
{
  acs_system_id: '...',
  name: 'Example Inc',
  external_type: 'kisi_organization',
  external_type_display_name: 'Kisi Organization',
  connected_account_ids: ['...'],
  ...
}
*/

systems = seam.acs.systems.list()

kisi_system = systems[0]

print(kisi_system)
# AcsSystem(
#   acs_system_id='...',
#   name='Example Inc',
#   external_type='kisi_organization',
#   ...
# )

systems = seam.acs.systems.list

kisi_system = systems.first

puts kisi_system

<?php
$systems = $seam->acs->systems->list();

$kisi_system = $systems[0];

echo $kisi_system->name; // Example Inc

var systems = seam.Acs.Systems.List();

var kisiSystem = systems[0];

Console.WriteLine(kisiSystem.Name); // Example Inc

var systems = seam.acs().systems().list();

var kisiSystem = systems.get(0);

System.out.println(kisiSystem.getName()); // Example Inc

curl -X 'POST' \
  'https://connect.getseam.com/acs/systems/list' \
  -H "Authorization: Bearer ${SEAM_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{}'

4 — List Entrances

Entrances represent the doors managed by the Kisi system. In the sandbox, this includes Front Door (online) and Back Door (offline, with restrictions enabled) in a place named Main Office.

const entrances = await seam.acs.entrances.list({
  acs_system_id: kisiSystem.acs_system_id,
})

console.log(entrances)
/*
[
  {
    acs_entrance_id: '...',
    display_name: 'Front Door',
    can_unlock_with_cloud_key: true,
    ...
  },
  ...
]
*/

entrances = seam.acs.entrances.list(
    acs_system_id=kisi_system.acs_system_id
)

print(entrances)

entrances = seam.acs.entrances.list(
  acs_system_id: kisi_system.acs_system_id
)

puts entrances

<?php
$entrances = $seam->acs->entrances->list(
  acs_system_id: $kisi_system->acs_system_id
);

print_r($entrances);

var entrances = seam.Acs.Entrances.List(
  acsSystemId: kisiSystem.AcsSystemId
);

foreach (var entrance in entrances)
{
  Console.WriteLine(entrance.DisplayName);
}

var entrances = seam.acs().entrances().list(
  AcsEntrancesListRequest.builder()
    .acsSystemId(kisiSystem.getAcsSystemId())
    .build()
);

System.out.println(entrances);

curl -X 'POST' \
  'https://connect.getseam.com/acs/entrances/list' \
  -H "Authorization: Bearer ${SEAM_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d "{\"acs_system_id\": \"${ACS_SYSTEM_ID}\"}"

5 — Grant a Cloud Key

To give a member access, create an Access Grant. An Access Grant is a single call that defines who gets access, where they can go, when access is valid, and how they get in. For Kisi, request the cloud_key access method to issue a cloud key — a web-based unlock attributed to that specific user. Seam provisions the underlying Kisi user and cloud-key credential for you, so you do not create Kisi users directly.

const frontDoor = entrances.find((e) => e.display_name === 'Front Door')

const accessGrant = await seam.accessGrants.create({
  user_identity: {
    full_name: 'Jane Guest',
    email_address: 'jane.guest@example.com',
  },
  acs_entrance_ids: [frontDoor.acs_entrance_id],
  requested_access_methods: [{ mode: 'cloud_key' }],
  starts_at: '2025-07-13T15:00:00.000Z',
  ends_at: '2025-07-16T11:00:00.000Z',
})

console.log(accessGrant)

front_door = next(e for e in entrances if e.display_name == "Front Door")

access_grant = seam.access_grants.create(
    user_identity={
        "full_name": "Jane Guest",
        "email_address": "jane.guest@example.com",
    },
    acs_entrance_ids=[front_door.acs_entrance_id],
    requested_access_methods=[{"mode": "cloud_key"}],
    starts_at="2025-07-13T15:00:00.000Z",
    ends_at="2025-07-16T11:00:00.000Z",
)

print(access_grant)

front_door = entrances.find { |e| e.display_name == "Front Door" }

access_grant = seam.access_grants.create(
  user_identity: {
    full_name: "Jane Guest",
    email_address: "jane.guest@example.com",
  },
  acs_entrance_ids: [front_door.acs_entrance_id],
  requested_access_methods: [{ "mode": "cloud_key" }],
  starts_at: "2025-07-13T15:00:00.000Z",
  ends_at: "2025-07-16T11:00:00.000Z"
)

puts access_grant

<?php
$front_door = array_values(array_filter(
  $entrances,
  fn($e) => $e->display_name === "Front Door"
))[0];

$access_grant = $seam->access_grants->create(
  user_identity: [
    "full_name" => "Jane Guest",
    "email_address" => "jane.guest@example.com",
  ],
  acs_entrance_ids: [$front_door->acs_entrance_id],
  requested_access_methods: [["mode" => "cloud_key"]],
  starts_at: "2025-07-13T15:00:00.000Z",
  ends_at: "2025-07-16T11:00:00.000Z"
);

print_r($access_grant);

var frontDoor = entrances.First(e => e.DisplayName == "Front Door");

var accessGrant = seam.AccessGrants.Create(
  userIdentity: new()
  {
    FullName = "Jane Guest",
    EmailAddress = "jane.guest@example.com",
  },
  acsEntranceIds: new List<string> { frontDoor.AcsEntranceId },
  requestedAccessMethods: new List<object> { new { mode = "cloud_key" } },
  startsAt: "2025-07-13T15:00:00.000Z",
  endsAt: "2025-07-16T11:00:00.000Z"
);

Console.WriteLine(accessGrant.AccessGrantId);

var frontDoor = entrances.stream()
    .filter(e -> "Front Door".equals(e.getDisplayName()))
    .findFirst()
    .orElseThrow();

var accessGrant = seam.accessGrants().create(
  AccessGrantsCreateRequest.builder()
    .userIdentity(UserIdentity.builder()
      .fullName("Jane Guest")
      .emailAddress("jane.guest@example.com")
      .build())
    .acsEntranceIds(List.of(frontDoor.getAcsEntranceId()))
    .requestedAccessMethods(List.of(
      RequestedAccessMethod.builder().mode("cloud_key").build()))
    .startsAt("2025-07-13T15:00:00.000Z")
    .endsAt("2025-07-16T11:00:00.000Z")
    .build()
);

System.out.println(accessGrant.getAccessGrantId());

curl -X 'POST' \
  'https://connect.getseam.com/access_grants/create' \
  -H "Authorization: Bearer ${SEAM_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d "{
    \"user_identity\": {
      \"full_name\": \"Jane Guest\",
      \"email_address\": \"jane.guest@example.com\"
    },
    \"acs_entrance_ids\": [\"${ACS_ENTRANCE_ID}\"],
    \"requested_access_methods\": [{\"mode\": \"cloud_key\"}],
    \"starts_at\": \"2025-07-13T15:00:00.000Z\",
    \"ends_at\": \"2025-07-16T11:00:00.000Z\"
  }"

A Kisi cloud key triggers a web-based unlock — the member opens the granted doors over the internet from a shareable link or an unlock button in your app, and each unlock is attributed to that member in the Kisi audit log. See Using Cloud Keys for details.

6 — Unlock a Door

Each Kisi door is also exposed as a device, which lets you trigger a remote unlock directly. Kisi processes the unlock through its cloud, so the action is fire-and-forget — Seam does not receive confirmation of the physical unlock from the device.

const locks = await seam.locks.list()

const frontDoorLock = locks.find(
  (l) => l.properties.name === 'Front Door',
)

// unlock the door
await seam.locks.unlockDoor(frontDoorLock.device_id)

locks = seam.locks.list()

front_door_lock = next(
    l for l in locks if l.properties["name"] == "Front Door"
)

# unlock the door
seam.locks.unlock_door(device_id=front_door_lock.device_id)

locks = seam.locks.list

front_door_lock = locks.find { |l| l.properties.name == "Front Door" }

# unlock the door
seam.locks.unlock_door(device_id: front_door_lock.device_id)

<?php
$locks = $seam->locks->list();

$front_door_lock = array_values(array_filter(
  $locks,
  fn($l) => $l->properties->name === "Front Door"
))[0];

// unlock the door
$seam->locks->unlock_door(device_id: $front_door_lock->device_id);

var locks = seam.Locks.List();

var frontDoorLock = locks.First(l => l.Properties.Name == "Front Door");

// unlock the door
seam.Locks.UnlockDoor(deviceId: frontDoorLock.DeviceId);

var locks = seam.locks().list();

var frontDoorLock = locks.stream()
    .filter(l -> "Front Door".equals(l.getProperties().getName()))
    .findFirst()
    .orElseThrow();

// unlock the door
seam.locks().unlockDoor(LocksUnlockDoorRequest.builder()
    .deviceId(frontDoorLock.getDeviceId())
    .build());

# 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}\"}"

Kisi does not support a remote lock action. Only unlock is available. Unlock requests against doors with geofence or reader-proximity restrictions may be rejected by Kisi.

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 systems 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:

Access Grants — the recommended way to manage access across providers
Using Cloud Keys
Receiving webhooks for device events
Core Concepts

If you have any questions or want to report an issue, email us at support@seam.co.

Overview

Smart Locks

Access Control Systems

Intercoms

Thermostats

Noise Sensors

Cameras

Other Devices

Get Started with the Kisi Access Control System

Overview

1 — Install Seam SDK

2 — Link Kisi System with Seam

Request a Connect Webview

Authorize Your Workspace

3 — Retrieve the ACS System

4 — List Entrances

5 — Grant a Cloud Key

6 — Unlock a Door

Next Steps

​Overview

​1 — Install Seam SDK

​2 — Link Kisi System with Seam

​Request a Connect Webview

​Authorize Your Workspace

​3 — Retrieve the ACS System

​4 — List Entrances

​5 — Grant a Cloud Key

​6 — Unlock a Door

​Next Steps

Overview

1 — Install Seam SDK

2 — Link Kisi System with Seam

Request a Connect Webview

Authorize Your Workspace

3 — Retrieve the ACS System

4 — List Entrances

5 — Grant a Cloud Key

6 — Unlock a Door

Next Steps