API Introduction

API Introduction

You are here:

Whenever a user performs an action on the marketplace platform, such as subscribing to a plan, it will automatically trigger an API call from the Kaiwoo provisioning API client. These API calls are performed against the API server of the service provider to allow the latter to keep track of any user interactions related to its service and respond accordingly.

Our API Architecture

For provisioning, Kaiwoo uses a Push API model. The Kaiwoo API acts as client and sends outgoing API requests to the service provider’s API server. Each incoming API requests is either responded to with an acknowledgement or a service configuration.

In practical terms, the Kaiwoo API allows for automated provisioning, configuration exchange & general data sync between the Kaiwoo platform and services providers.


Our API consists of several endpoints distinguished by sets of specific user actions. In order to integrate with Kaiwoo and receive Provisioning API calls, a service provider needs to implement those endpoints on its own API server. Depending on the type of service, not all endpoints may be needed. Therefore, a service provider should select the endpoints relevant to its use case.

In order for the Kaiwoo marketplace to perform provisioning for a service provider, a service-specific Provisioning URL is created. The Provisioning URL is composed of two parts:

Provisioning URL = base URL + endpoint path

The base URL is defined by the service provider and points to its Provisioning API server. Configuration of the base URL can be done via the Kaiwoo console. To learn how to get started on the Kaiwoo console, please follow this link. On the other hand, the various endpoint paths are defined by Kaiwoo.

The following endpoints and related user actions are covered in Kaiwoo’s API documentation:

  1. Subscriptions endpoint: the user subscribes to a plan on the marketplace, updates or terminates an existing subscription;
  2. Networks endpoint: the user activates a service on one or multiple networks, updates or deletes networks associated with a subscription;
  3. SSIDs endpoint: the user activates a service on one or multiple SSIDs, updates or deletes SSIDs associated with a subscription;
  4. Devices endpoint: the user activates a service on networks containing one or multiple devices, updates or deletes devices associated with this network.

The API calls that can be performed are named CREATE, UPDATE and DELETE. These calls inform the service about anything related to the subscription life cycle.

Provisioning API sample code can be found here for your reference.

Subscription Life Cycle

When a user purchases a plan on the marketplace, a subscription is created on the Kaiwoo platform. The service provider offering the plan will be informed of the subscription using the subscription CREATE call. When the user then activates the service on one or multiple networks, the network CREATE call is performed. During the lifetime of a subscription, the user may apply changes to its network. This event triggers the UPDATE call, allowing the service provider to keep track of any changes occurring on the user’s side. The service expires at the end of the subscription billing period if not renewed by the user. The DELETE call informs the relevant provider that a subscription has been terminated. A user has the option to purchase a new plan and start another subscription at any point in time.

To better understand this concept please see the example below showing a simplified life cycle of a subscription.

To start configuring your API server, please follow the information shown in the Subscriptions endpoint article.

Table of Contents