Registration and authentication

To interact with the API, you must obtain an authentication_token for the user you'll be working with. For that purpose, you need to create a new user account and sign in to Kisi.

Create a user account

1. Create a user account using a name, email, and password
2. Accept the Terms & Conditions. A profile image can also be added.
3. Click on Confirm Email Address in the confirmation email

This takes you to the API confirmation URL, which, as stated in the API confirmation call specification, has this format:

https://api.kisi.io/users/confirmation?confirmation_token=L3xdbk8cyouQfkAuXxFY&domain=

Verify the email

1. Build the API confirmation URL as explained above
2. Send a GET request to the API

This will confirm the email and give a response that will contain the user id, name and, email.

If the confirmation email has not arrived after 2-5 minutes, another one can be requested through a POST call to the API, sending the domain (if applicable), and the email.

For Kisi users, this is done through the Request Confirmational Email page.

Sign in

Once you have signed up and confirmed your email, you can now sign in to create an authentication_token.

1. Sign in using the email and password, through a POST call to /users/sign_in or /logins
2. If the login is successful, the response will contain the authentication_token field/ Its value will be needed for the subsequent API calls.

Each time you sign in, this token will be different. If the login is not successful, you will get an error message.

Integration partner headers

We recommend that integration partners include these headers in requests to the Kisi API:

X-Kisi-Integration-Identifier: <name of integration partner>
X-Kisi-Integration-Contact: <contact(email) of the integration partner>

Multiple accounts on mobile

To manage multiple accounts on mobile, please refer to this guide

Generate a Kisi API key

You need to have organization administrator or organization owner rights to create an API key. We recommend creating API keys from the organization owner's account, to avoid the API key becoming invalid when an organization admin loses their admin rights.

1. Sign in to Kisi
2. On the top right corner, click on your name and click on My Account
3. Next, select the API tab and click on Add API key
4. Enter your name, your Kisi password, and your verification code and click Add
5. Copy the API key shown on the screen and click Close

Please note that you can't change your API key. If you don't remember the password or you want to change the name, you will have to create a new API key.

White labeling

White labeling allows you to transparently integrate Kisi functionalities into your own applications, without requiring users to register for a Kisi account.

This allows your users, for instance, to unlock Kisi-enabled doors with your app.

Creating white label users

For creating white-label users, the authorization token of the organization owner or an admin is required. You will need to make a call to the members endpoint, sending the authorization token and a request payload:

{
  "member": {
    "email": "email-of-the-user@example.com",
    "confirm": true,
    "send_emails": false
  }
}

The user will be created and automatically confirmed and will not receive notifications from Kisi. Omitting the send_emails field from the request payload will result in the user receiving emails from Kisi. By default, we recommend setting the send_emails to false.

Creating logins on behalf of users

Kisi device logins can be created on behalf of users in an organization. To do that, send a request to the Kisi API login endpoint with the authorization token of the organization owner or an admin and the following payload:

{
  "login": {
    "type": "device",
    "email": "email-of-the-user@example.com"
  }
}

The login can then be used subsequently to make requests to the Kisi API on behalf of the user.