Kolibri Identity Server
The Kolibri platform consists of several API’s. These API’s are all protected, meaning a client requires some form of authorization and authentication to access these API’s. This protection is provided by the Kolibri Identity Server. This Identity Server must be used by clients to obtain an access token (JWT). This access token then can be used to access predefined resources (the real estate agencies that have given consent to the client) and the API endpoints that the client has access to.
The Kolibri Identity Server is built on the OAuth 2.0 and OpenID Connect protocols. More information about these protocols can be found here: https://tools.ietf.org/html/rfc6749 and https://openid.net/connect/.
As a client is it possible to be either a Server to Server client (2-legged client) or a Client to Server client (3-legged client).
A server to Server client is a client that performs actions on data without a user (realtor) triggering this action. It does not require a user to login using its Kolibri account. This type of client uses a client ID and client secret to get access tokens from the Kolibri Identity Server.
A client to Server client is a client that requires the user to login using its Kolibri account. The client then makes requests to the API, triggered by the user, on the users’ data in the Kolibri API. This type of client uses 3-legged Authentication to obtain a JWT, meaning that the user Logs in into the Identity Server to obtain an access token for your application. So, this is done without a client secret.
The Kolibri API is the core API of the Kolibri platform. It has (like all API’s in Kolibri) a RESTful architecture. This means that all resources are obtained and mutated using HTTP requests. A resource is obtained using a HTTP-GET request on a specific endpoint. This data can then be mutated by your AppXchange client. These changes can then be persisted in the Kolibri API. Every request that is performed on the Kolibri API must have an access token that is obtained at the Kolibri Identity Server.
Real estate agencies can determine which AppXchange clients have access to their data. In the Kolibri AppXchange Store, which can be found in the Kolibri Web UI, they can find all available AppXchange clients. Then they can give consent to a specific client. Only when a real estate agency has given consent, the AppXchange client can obtain and mutate data for this real estate agency.
The Kolibri API is built like a multi-tenant-environment. Each real estate agency is a distinct tenant. So, AppXchange clients must provide the unique real estate agency ID in each request that is made on the Kolibri API. You can read more about the Kolibri API here.
To integrate even better with the Kolibri platform it is possible to add your own widgets in the Kolibri UI web client. On multiple locations in the app it is possible for you to show you widget in an Iframe. When a realtor loads a page where your widget should be shown, the Kolibri Web UI client makes a request to your AppXchange client’s server. You can then return an HTML page which is then shown in the Kolibri UI. You can read more about widgets here.
Some AppXchange partners want to be notified over HTTP when events occur, such as . A WebHook is a useful feature to achieve this.
Each time an event occurs Kolibri POSTS a message using HTTP(S) to your server, using a pre-configured URI. The AppXchange partner must provide the URI so it can be configured in our platform.
You can find more details about WebHooks at this page.
If your application requires settings that can be set in Kolibri by the users, it is possible to add custom settings for your AppXchange client in the Kolibri UI web client. Realtors can use this page to view and edit your clients settings. It is possible to have company-wide settings or employee specific settings. These settings can then be obtained from the Rest-based Authorization API by your AppXchange client. It is possible to obtain webhooks when a setting is mutated, so your AppXchange client can obtain the modified settings.