API Guideline

First steps with the KIWI API

Getting started

Before you can start testing and using our API, you need to become a KIWI customer. There are two ways to do so:

1. You already have a KIWI installation in a property and KIWI Portal access. Then, you can start using the API right away by reading our API Documentation. However, to keep your productive processes unharmed, you may want to consider our second option.
2. Get a KIWI Developer Kit including test hardware for making your first steps with our API.

A user account is required for most interactions with the KIWI API. An account can be obtained by:

• Being given an account by an administrator or manager who is using the KIWI Portal. For productive integrations, the administrator is usually a member of the organisation owning or at least controlling access to the physical access points (doors, gates, safes, …).
• Creating an account using API endpoints.

Next, get your admin user accounts ready:

In case you’ve bought our Developer Kit

• Your root account credentials are as follows:

1 Username: $TESTER_MAIL_ADDRESS
2 Initial Password: $TESTER_PASSWORD

• Also, the above account is owner and has admin permissions on the following sensors (see the QR codes to identify the sensors)

1 UUID: $UUID_SENSOR (Sensor ID: $SENSOR_ID)
2 UUID: $UUID_SENSOR_2 (Sensor ID: $SENSOR_ID_2)

If you’re using your own test environment, we recommend having a test user account with at least manager permissions to some test access points. If you are unsure about your setup or need help, don’t hesitate to contact service@kiwi.ki.

Establish an authenticated user session – POST /v1/session: Before most API requests can be made, a login session must be started by providing your test user’s username and password. A session key will then be given back from the API, which can be used for authentication on further API requests.

1 curl --location --request POST 'api.kiwi.ki/v1/session' \
2 --header 'Content-Type: application/json' \
3 --data-raw \
4 '{"password": "example_string","username": "user@example.com"}'

Important Concepts

Understand the most important concepts of the KIWI API:

• Sensor: A door in the physical world that can be accessed through the API is represented in the KIWI system by a “sensor”.
• User: Every door or sensor in the KIWI system can be accessed by registered users only. Like in most other digital services, a KIWI user has credentials to identify him or herself so that KIWI can determine who has access to and control over which assets. As you’ve noticed in the previous step, our API uses session keys to authenticate and authorize users.
• Permissions: KIWI uses permissions to determine and manage the degree of control a given user has over a given door (sensor). The KIWI API knows the following permission levels for sensors:

• You may also come across the concept of the sensor owner (“IS_OWNER”), which represents the actual owner of the door in the physical world. Since it is not a permission level, it will not allow a user to open, but, for example, to see who has access to the door.
• Organisations: Finally, you should know about organisations. In the KIWI system, an organisation is a group of users that share a common characteristic or interest, e.g. employees of the same housing company. Like in the real world, organisations can have members and must have an owner (to administrate the organisation). Organisations help us to aggregate resources in the KIWI system and make them available to the specific user group that forms the organisation. Hence, organisations limit the scope of resources that can be requested via any given API request on behalf of a user. Example: On behalf of user A, you want to grant a Guest permission to his apartment door to another user B. In order to do so, user B must be known of the same organisation as user A in the KIWI system.

With these concepts under your belt, now it’s a good idea to read the KIWI API Documentation and understand the endpoints available to you.