Skip to main content

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.

Signing up#

Anyone wishing to use the Kisi dashboard or API will need to create a new Kisi account. To create a new account through the API calls, follow the steps below.

If you want to integrate Kisi in your application, you might be interested in using our white labeling support. See more in the white labeling section in this guide.

Create a user account#

Create a user account using a name, email, and password, with acceptance to the Terms & Conditions. A profile image can also be added.

A confirmation email will be sent to the email address, with a Confirm Email Address button that 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=

Confirmation Email and Token Parameter

Verify the email#

To verify the email, click on the Confirm Email Address button or copy the link confirmation_token parameter, build the API confirmation URL as explained above, and 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.

Signing in#

Users that have signed up and confirmed their email, can now sign in to create an authentication_token.

Sign in using the email and password, through a POST call to /users/sign_in or /logins. If the login is successful, the response will contain the authentication_token field, whose 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, the response will be an object showing an error message.

Creating an API key#

To create API keys, log in to the Kisi Dashboard. Then click on your profile on the top right and select "API". There you will see an "Add API key" button. By clicking on it, a pop-up will appear and you will have to give a name and a password to your new API key.

After creating your API key, you can now use it in your Kisi API calls. You will only be able to delete your API key, no changes can be made to it. If you don't remember the password or you want to change the name, you will have to create a new API key.

API keys can only be created by entire place admins or place owners. They should only be created by place owners to avoid the API key becoming invalid when a place admin loses their admin rights.

For Organization subscriptions, API keys can only be created by Organization Administrators or Organization Owners. As a best practice, we recommend creating API keys from the Organization Owners account, to avoid the API key becoming invalid when an Organization Admin loses their admin rights.

White labeling#

For some integrations, you'll maybe want to take advantage of our white labeling support. White labeling allows partners to integrate Kisi functionalities into their own applications without requiring users to register for a Kisi account – this can happen transparently.

With such an integration, users will be able to, for instance, unlock doors that have Kisi locks installed. When the user tries to unlock the door with the partner’s app, a request would be sent to the Kisi API to trigger the unlock.

Creating white label users#

For creating white-label users, the authorization token of the organization owner is required. You will need to make a call to the members endpoint, sending, at least, 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.

Check the authentication section of our Getting Started guide for more information about the authorization token.

Creating logins on behalf of users#

Kisi device logins can be created on behalf of users in an organization. The login can then be used subsequently to make requests to the Kisi API login endpoint) on behalf of the user. The authorization token of the organization owner is required and the basic payload is:

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