Skip to main content

Getting started

This guide will take you through the basic configuration and domain concepts in a practical way, so you can start making calls to the API right away and get an idea of how to work with it.

Before starting, make sure to check out the brief heads up guide.

Setting up#

To start interacting with the Kisi API, let's set up the environment that will allow us to use the endpoints.

Clients and requests#

To interact with the Kisi API, you have to dispatch secure HTTP requests. Most programming languages have built-in client libraries for creating HTTP requests and dealing with their responses.

If you're using JavaScript, we provide an official API client. It supports all of the API's endpoints. It also provides authentication helpers and sets relevant JSON headers as well as authentication headers automatically so you don't have to.

Format and headers#

The Kisi API supports JSON only, so please set Accept and Content-Type headers of your API calls to application/json. All requests and responses will use JSON as the format for any data encompassed in the body of requests and responses.

<METHOD> <URL> HTTP/1.1
Accept: application/json
Content-Type: application/json

Authentication#

Most calls to the API will require an authenticated user. If such a user is not present, you will receive a 401 response. To sign in and be able to authenticate future calls, you must:

  1. Create a user and confirm it.
  2. Create a login register by signing in. You will receive an access token that must be included in the Authorization header field on subsequent calls to the API:
<METHOD> <URL> HTTP/1.1
Authorization: KISI-LOGIN <secret>
Accept: application/json
Content-Type: application/json

For more details, check the Registration and authentication guide.

Rate limiting#

For authenticated API requests, you can make up to 5 requests per second, per user. Note that the limit applies per user, so requests made using different logins for the same user share the same quota.

For unauthenticated requests, you can make up to 5 requests per second, per IP address. If you exceed the rate limit, a 429 response will be returned.

The following endpoints have custom rate limits:

EndpointLimit
GET /events1 per second
note

We reserve the right to change these limits as needed to ensure availability.

Best practices#

To avoid rate problems, always apply these rules:

  • If you're making requests for a single user, do so serially, not concurrently.
  • If you're making a large number of requests for a single user, wait at least one second between each request.

Deprecations#

In the event that some part of the API has to be deprecated, we act as follows:

  1. Return the Deprecation header with the date of when the endpoint is deprecated.
  2. Return the Sunset header with the date of when the endpoint can be expected to not function anymore.
  3. When the Sunset date is reached, the endpoint may go away at any time.

Let's make those calls#

Now that we have set up the working environment, we can start interacting with the API. From now on, we will present basic examples to help you obtain your first successful responses from the endpoints. Each example is presented in two formats:

  1. As an object that you can use, for example in the raw option from the Body tab in Postman.
  2. As a JavaScript call, in case you are using our official API client.

To make a basic Kisi set up, you need to:

  1. Create a user account.
  2. Create a place.
  3. Create a controller and a reader.
  4. Create a lock (and unlock it for fun).
  5. Share access with the user.

Registration and authentication#

The first thing you need to do is create a new user and sing in. To become a Kisi user you need:

  1. Sign up with a name, an email address, a password and accepting the terms and conditions.
  2. Verify your email address. Since we tie access rights to email addresses (required, for now), it is imperative that users confirm their email addresses before signing in.

For more details, please check the Registration and authentication guide.

Signing up#

The Body of the HTTPS request to create a User object, can be as simple as:

{
"user": {
"name": "First Last",
"email": "email@example.com",
"password": "test1234",
"terms_and_conditions": true
}
}

Or with the JavaScript client:

kisiClient
.signUp("email@example.com", "test1234")
.then((user) => console.log(user)) // the created user
.catch((error) => console.log(error)); // any error

Within seconds you should receive a confirmation email. Follow its instructions to confirm. If you wish to programmatically parse the email and confirm the user, you need to extract the confirmation token from the confirmation URL, which looks like this:

https://web.kisi.com/users/confirmation?confirmation_token=bQBxyMTKyX5FvzARM16M

The token here is bQBxyMTKyX5FvzARM16M. Use it when you call the confirmation endpoint.

For more details, check the Signing up section from the Registration and authentication guide.

Signing in#

Once the user has been confirmed, sign in to create a Login object. This object will contain a secret token that must be used for subsequent, access restricted calls to the API.

The payload of the request can be as this one:

{
"user": {
"email": "email@example.com",
"password": "test1234"
}
}

And the endpoint you should use is https://api.kisi.io/users/sign_in as explained in the Signing in section of the Registration and authentication guide. For more details about the ´Login´ object, check the Create a Login endpoint reference.

And the payload of the response will contain the secret token and will look like this:

{
"secret": "secret"
}

If you do it with the JavaScript client, it will automatically set the authentication header for subsequent requests. The call will look like this:

kisiClient
.signIn("email@example.com", "test1234")
.then((user) => console.log(user))
.catch((error) => console.log(error));

If you're using the JavaScript SDK, you're all set. If you're creating your HTTP requests manually, set the Authorization header on subsequent calls:

Authorization: KISI-LOGIN <token>

Signing out#

At this point, it can be handy to know how to sign out, so you don't worry about leaving open sessions or for signing in again if needed.

To sign out, just call the sign out endpoint, https://api.kisi.io/users/sign_out, with the Authorization header and token - a payload is not required.

Or, with the JavaScript client:

kisiClient
.signOut()
.then((user) => console.log(user))
.catch((error) => console.log(error));

Create a place#

To create a place, pass in the necessary attributes to a POST call to the create place endpoint. The API will return the place you created, remember to write down the id so you can use it later. Example payload:

{
"place": {
"name": "My 1st Kisi Place",
"address": "63 Flushing Ave, New York City 11205 USA"
}
}

With the JavaScript client:

const place = {
name: "My 1st Kisi Place",
address: "63 Flushing Ave, New York City 11205 USA",
};
kisiClient
.post("places", { place })
.then((place) => console.log(place)) // the created place
.catch((error) => console.log(error)); // any error

Now that you have created a place, we can go on to creating controllers and locks.

tip

If you wish to grant access to a user, that user does not need to create a place. Instead, you share an existing place with the user by creating a share (see Sharing access).

Controllers and readers#

While it is possible to create controllers and readers using the API, usually this approach alone won't work as your devices won't have any Wi-Fi credentials when they are shipped.

Therefore, to create a Kisi device, you have to perform a blinkup with your Android or iOS app first. Once the blinkup has been completed, the app will create the controller and the reader for you.

Check the support article about BlinkUp for more information about it.

Create a lock and unlock it#

The final missing piece on our journey towards our first unlock is the lock. It represents anything in the real world that can be accessed using a Kisi router. To create a lock, simply send a post request to the create locks endpoint. Example payload:

{
"lock": {
"name": "My 1st Kisi Lock",
"place_id": 1
}
}

With the JavaScript client:

const lock = {
name: "My 1st Kisi Lock",
place_id: 1,
};
kisiClient
.post("locks", { lock })
.then((lock) => console.log(lock)) // the created lock
.catch((error) => console.log(error)); // any error

With the lock created, let's unlock it!. We don't need to send along any values to the unlock locks endpoint unless you've enabled certain restrictions, e.g. reader restrictions. In that case, you need to send along your client context - find out more about this in the API docs. With the JavaScript client:

kisiClient
.post("locks/1/unlock", {})
.then((result) => console.log(result)) // the result
.catch((error) => console.log(error)); // any error

If your unlock failed, you will get an error result back. Check the errors section of the documentation for more information.

Sharing access#

Sharing access works based on email addresses. You grant access to users by creating groups and sharing access with user to these groups.

Groups#

For more than just simple scenarios, you will probably want to grant access more granularly based on real world access permissions of your users. For example, guest users should only be allowed to access between 9AM and 5PM on weekdays, whereas members should be allowed access at all times. Also, guests may not access garage doors, while members may.

This is where groups come in handy. Groups share a specific set of locks with a specific set of users that you define. For example:

  • Group Guests: access from 9AM-5PM on weekdays sharing lock "Entrance" to all guest users.
  • Group Members: access from 9AM-5PM every day sharing lock "Entrance" and "Garage" to all member users.

Let's create the members group by posting a request to the create groups endpoint with the following payload:

{
"group": {
"name": "Members",
"time_restriction_enabled": true,
"time_restriction_time_slots": {
"weekday": 1,
"allowed_from": 540,
"allowed_until": 1020
},
"time_restriction_time_slots": {
"weekday": 2,
"allowed_from": 540,
"allowed_until": 1020
},
"time_restriction_time_slots": {
"weekday": 3,
"allowed_from": 540,
"allowed_until": 1020
},
"time_restriction_time_slots": {
"weekday": 4,
"allowed_from": 540,
"allowed_until": 1020
},
"time_restriction_time_slots": {
"weekday": 5,
"allowed_from": 540,
"allowed_until": 1020
},
"place_id": 1
}
}

We omit the JavaScript examples from now on - check previous examples on how to use the JavaScript client SDK.

With the group created, you can add locks to it. Assuming that you already created a lock in the previous parts of this section let's focus on the call to assign a lock to a group. Simply post a request to the create group lock endpoint with this payload:

{
"group_lock": {
"group_id": 1,
"lock_id": 1
}
}

Now that you have created a group and added a lock to it, you'll want to add users to this group. To do so, create a share that grants access to this group:

{
"share": {
"email": "member@example.com",
"group_id": 1
}
}

And done!