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, if you allow it, 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.

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 resolves the user and their device login, then unlocks the door as that user
5. Every attempt, successful or not, appears in the connector's unlock logs

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 detects it and repairs it before retrying once.

Grant access automatically

The Grant Access Automatically setting controls what happens when a user doesn't have access to the door yet:

• On - Kisi grants the user access to the door on their first unlock. The connector creates a group for the door, named Workflows: Door followed by the door name, and adds the user to it.
• Off - only users who already have access to the door in Kisi can unlock it. For everyone else, the request fails with the error Kisi returns, for example 403 when the user has no access. No groups or access rights are created.

The setting is off for new installations. Keep it off if you manage access in Kisi yourself, for example with groups, schedules, or another integration, and want the partner system to unlock only doors users are already allowed to open. Turn it on if the partner system decides who may open which door.

info

In both modes, Kisi creates the user if no Kisi user exists for the email yet. User creation counts towards your organization's user quota.

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 Integration Setup tab, click Generate API Key
6. Copy the API key and store it securely

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. Optional: turn Grant Access Automatically on if users should get access to doors on their first unlock
8. Share the API key, the endpoint URL, and the lock IDs of your doors with the partner system

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 from the connector page:

1. On the Integration Setup tab, click Test
2. Select a Place and a Lock
3. Enter a Partner User ID, an Email, and the API Key
4. Click Unlock

The dialog shows whether the door unlocked or the error that was returned, and the attempt appears in the unlock logs. The values you enter in the dialog aren't stored.

Send unlock requests

Send a POST request with a JSON body to the unlock endpoint. The endpoint URL is shown with a copy button on the Integration Setup tab.

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.
email	string	Yes	The user's email address
lockId	integer	Yes	The Kisi lock ID of the door to unlock
name	string	No	Display name for the Kisi user. Defaults to the email.
location	object	No	{ "latitude": number, "longitude": number } of the user, used by geofenced locks. Omit it if it's unknown.

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 readable 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" }
  }
}

Status	Meaning	What to do
401	The API key is missing, wrong, or was rotated, or the integration is disabled	Check the API key. Don't retry until it's fixed.
403	The user can't open the door, or the organization reached its user quota	Check the user's access or the user quota in Kisi
404	The lock ID or user can't be found	Check the lock ID and email
409	Another unlock for the same user and door is still running	Wait a moment and retry
500	Kisi couldn't complete the setup or the unlock	Retry with backoff. If it keeps failing, contact our support team

With Grant Access Automatically off, a rejected unlock returns the status and message Kisi returned, so the partner app can show the user why the door didn't open.

Review unlock logs

Every unlock attempt is logged with the time, the partner user ID, name, email, lock ID, result, and the error message for failed attempts.

1. Open the Kisi Unlock Connector integration
2. Click the Unlock Logs tab
3. Optional: set From and To to show attempts in a time range
4. Optional: click Export CSV to download the logs in the selected range

Logs show 100 attempts per page. One export contains up to 10,000 of the newest attempts in the selected range. To export more, narrow the time range and export again.

The unlock logs 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. Copy the new API key and share it 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.