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:
- a. 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.
- b. 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 systemby a “sensor”.
- User: Every door or sensor in the KIWI system can be accessed by registered users only. Like in most otherdigital services, a KIWI user has credentials to identify him or herself so that KIWI can determine who hasaccess to and control over which assets. As you’ve noticed in the previous step, our API uses session keys toauthenticate and authorize users.
- Permissions: KIWI uses permissions to determine and manage the degree of control a given user has over agiven door (sensor). The KIWI API knows the following permission levels for sensors:
| Permission Level | Explanation |
|---|---|
| IS_GUEST | The lowest permission level that allows to open thesensor it is linked with. |
| IS_HOST | A host permission allows a user to open the sensor itis linked with, and to grant other users Guestpermissions to that sensor. |
| IS_MANAGER | A manager permission allows a user to open thesensor it is linked with, grant other users Host andGuest permissions to that sensor, and see moredetailed information about the sensor, e.g. deviceanalytics |
| IS_ADMIN | The highest permission level that allows a user toopen the sensor it is linked with, and to grant otherusers Manager, Host and Guest permissions to thatsensor and see more detailed information about thesensor, e.g. device analytics |
- You may also come across the concept of the sensor owner (“IS_OWNER”), which represents the actualowner 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 groupof users that share a common characteristic or interest, e.g. employees of the same housing company. Likein 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 specificuser group that forms the organisation. Hence, organisations limit the scope of resources that can berequested via any given API request on behalf of a user. Example: On behalf of user A, you want to grant aGuest permission to his apartment door to another user B. In order to do so, user B must be known of thesame 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.