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.
To start interacting with the Kisi API, let's set up the environment that will allow us to use the endpoints.
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.
JSON headers as well as authentication headers automatically so you don't have to.
The Kisi API supports
JSON only, so please set
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.
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:
- Create a user and confirm it.
- Create a login register by signing in. You will receive an access token that must be included in the
Authorizationheader field on subsequent calls to the API:
For more details, check the Registration and authentication guide.
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:
|1 per second|
We reserve the right to change these limits as needed to ensure availability.
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.
In the event that some part of the API has to be deprecated, we act as follows:
- Return the
Deprecationheader with the date of when the endpoint is deprecated.
- Return the
Sunsetheader with the date of when the endpoint can be expected to not function anymore.
- When the
Sunsetdate is reached, the endpoint may go away at any time.
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:
- As an object that you can use, for example in the
rawoption from the
Bodytab in Postman.
To make a basic Kisi set up, you need to:
- Create a user account.
- Create a place.
- Create a controller and a reader.
- Create a lock (and unlock it for fun).
- Share access with the user.
The first thing you need to do is create a new user and sing in. To become a Kisi user you need:
- Sign up with a name, an email address, a password and accepting the terms and conditions.
- 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.
Body of the
HTTPS request to create a
User object, can be as simple as:
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:
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.
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:
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:
HTTP requests manually, set the
Authorization header on subsequent calls:
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.
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:
Now that you have created a place, we can go on to creating controllers and locks.
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).
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.
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:
If your unlock failed, you will get an error result back. Check the errors section of the documentation for more information.
Sharing access works based on email addresses. You grant access to users by creating groups and sharing access with user to these 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:
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:
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: