Unlock doors from your app with the Kisi Unlock Connector

The Kisi Unlock Connector lets a partner system, such as a membership, booking, or coworking platform, unlock a Kisi door for one of its users with a single API call. Kisi takes care of everything the unlock needs behind the scenes: it creates the Kisi user if needed, sets up a device login, and grants the user access to the door. Your system only ever sends unlock requests.

Every unlock is attributed to the individual user, not to an admin, so your Kisi event history shows exactly who opened which door.

info

In Kisi, the connector's app page is headed Workflows.

How it works

1. An organization administrator installs the Kisi Unlock Connector and generates an API key
2. The administrator shares the API key and the Kisi lock IDs of the doors with the partner system
3. When a user taps Unlock in the partner app, the partner system sends the user's ID, email, and the lock ID to the unlock endpoint
4. Kisi makes sure the user, their device login, and their access to the door exist, then unlocks the door as that user
5. Every attempt, successful or not, appears under Unlock requests on the app page

The first unlock for a new user and door takes a few seconds, because Kisi sets everything up. Later unlocks reuse that setup and are fast. If something in the setup is changed or removed in Kisi, the connector recreates it before retrying once.

Access is granted automatically

The connector has no settings. Any user your partner system sends an unlock request for gets access to the requested door. On a user's first unlock of a door, Kisi adds the user to a group named Workflows: Door followed by the door name, which gives them access to that door.

To decide who may open which door, control which unlock requests the partner system sends.

What the connector creates in Kisi

• Users: if no Kisi user exists for the email, the connector creates one, without sending an invitation email. User creation counts towards your organization's user quota. If a Kisi user with that email already exists, the connector uses that user and doesn't change their name.
• Device logins: each user gets a device login named Workflow Login, which appears on the user's logins
• Groups: each door gets one group named Workflows: Door followed by the door name, shared by all users who unlock that door
• Memberships: users are added to the door's group as basic members, without a notification

Emails are trimmed and converted to lowercase before use, so Jane@Example.com and jane@example.com are treated as the same user.

Prerequisites

• Kisi organization administrator rights
• A partner system that can send HTTPS requests from its backend
• The Kisi lock IDs of the doors you want to unlock

Set up the integration

1. Sign in to Kisi
2. Click the integrations icon (3x3 grid of dots) > Add Integration
3. Enter a name, open the Type dropdown and select Kisi Unlock Connector
4. Click Add and follow the steps to install the connector
5. On the Workflows page, API key shows Not configured. Click Generate API key
6. In the API key generated dialog, copy the API key, store it securely, and click Done

warning

The API key is shown only once. Kisi stores only a hash of it, so it can't be displayed again. If you lose it, rotate the key to get a new one.

7. Share the API key, the endpoint URL https://marketplace.kisi.io/trpc/workflows.unlock, and the lock IDs of your doors with the partner system

Each installation has one API key. After you generate it, API key shows Configured and only Rotate is available.

The lock ID is the number in the lock's URL in the Kisi dashboard. Store the lock ID on the matching door, room, or location record in the partner system, so that every unlock request targets the right door.

Test the integration

Before you go live, send a test unlock with the curl command in Send unlock requests. Use your API key, a test lock ID, and a test email address. The test user is created in Kisi and added to the door's group, like any other user. The attempt appears under Unlock requests on the Workflows page.

Send unlock requests

Send a POST request with a JSON body to the unlock endpoint, https://marketplace.kisi.io/trpc/workflows.unlock:

curl -X POST https://marketplace.kisi.io/trpc/workflows.unlock \
  -H "Authorization: Bearer <API key>" \
  -H "Content-Type: application/json" \
  -d '{
        "remoteId": "member-9f2c",
        "email": "jane@example.com",
        "lockId": 456,
        "name": "Jane Doe",
        "location": { "latitude": 40.7128, "longitude": -74.006 }
      }'

Field	Type	Required	Description
remoteId	string	Yes	The partner system's stable ID for the user. Keep it the same even if the user's email changes. Can't be empty.
email	string	Yes	The user's email address. Can't be empty.
lockId	integer	Yes	The Kisi lock ID of the door to unlock. Must be a positive integer.
name	string	No	Display name for a newly created Kisi user. Defaults to the email. Ignored if a Kisi user with the email already exists.
location	object	No	{ "latitude": number, "longitude": number } of the user, used by geofenced locks. Latitude must be between -90 and 90, longitude between -180 and 180. Omit it if it's unknown.

API keys have the format ha_<number>_<64 hexadecimal characters>. A key in any other format, for example one truncated while copying, or an Authorization header without Bearer , returns 401.

A successful response means the door was unlocked:

{ "result": { "data": { "success": true } } }

If a user's email changes in the partner system, keep sending the same remoteId with the new email. Kisi links the remoteId to the Kisi user for the new email and continues.

warning

Send unlock requests only from the partner system's backend. Never include the API key in a mobile app or website code, where it could be extracted.

Handle errors

Failed requests return an HTTP error status and a JSON body with a message in error.message and the status in error.data.httpStatus:

{
  "error": {
    "message": "The organization has reached its user quota. Cannot create new users.",
    "data": { "code": "FORBIDDEN", "httpStatus": 403, "path": "workflows.unlock" }
  }
}

error.message is always one of a fixed set of messages, for example Unlock was denied. for a rejected unlock. The underlying message from Kisi isn't returned to the partner system. Administrators can see it in the Message column under Unlock requests.

Status	Result code	Meaning	What to do
400	-	The request body is invalid, for example remoteId or email is missing or empty, or lockId isn't a positive integer	Fix the request. Don't retry it unchanged.
401	-	The API key is missing, malformed, wrong, or was rotated, the integration is disabled, or the app was uninstalled	Check the API key. Don't retry until it's fixed.
403	QUOTA_EXCEEDED	The organization reached its user quota (The organization has reached its user quota. Cannot create new users.)	Free up or add users in Kisi
403	UNLOCK_DENIED	Kisi rejected the unlock (Unlock was denied.), for example because of a reader restriction	Check the Message column under Unlock requests for the reason
404	LOCK_NOT_FOUND	The lock ID doesn't exist in your organization	Check the lock ID
409	UNLOCK_IN_PROGRESS	Another unlock for the same email and lock is still running	Wait a moment and retry
500	UNLOCK_FAILED and others	Kisi couldn't complete the setup or the unlock	Retry with backoff. If it keeps failing, contact our support team

Review unlock requests

Every unlock attempt is logged, including requests rejected because another unlock was still running.

1. Open the Kisi Unlock Connector integration
2. Unlock requests are listed under Unlock requests on the Workflows page, newest first
3. Click Load more to see older attempts

The list shows 100 attempts at a time, with the columns Time, Remote ID, Name, Email, Lock ID, Message, and Result. Result shows the result code and HTTP status, for example UNLOCK_DENIED (403). Message shows the message Kisi returned for failed attempts.

Unlock requests appears only after an API key has been generated. Before that, the page shows "Generate an API key to start accepting headless unlock requests".

The unlock requests are available only to Kisi administrators in the dashboard. The partner system's API key can't read them.

Rotate the API key

Rotate the API key if it might have leaked, or when you stop working with a partner system.

1. Open the Kisi Unlock Connector integration
2. Click Rotate next to API key
3. Confirm with Rotate
4. In the API key generated dialog, copy the new API key and click Done
5. Share the new API key with the partner system

warning

Rotating immediately invalidates the old API key. The partner system can't unlock doors until it uses the new key.

Revoke access

To stop a partner system from unlocking doors, rotate the API key or uninstall the app.

Removing a user's access in Kisi doesn't block future requests. If you delete a Workflows: Door group, remove a user or a lock from it, delete the user, or delete the user's Workflow Login, the connector recreates it on the next unlock request for that user and door. To stop a single user, block them in the partner system instead.

Uninstall the connector

After you uninstall the connector, the API key stops working and requests return 401.

Uninstalling doesn't remove what the connector created in Kisi: the users, the Workflows: Door groups, their memberships, and the Workflow Login device logins stay in your organization. Remove them manually if you no longer need them.