Device Manager API

This page describes the method to use the Thingpark Device Manager through its API's.

The easiest way to use the Thingpark Device Manager is through the web interface found on https://www.kpn-lora.com/deviceManager/. This web interface gives you the possibility to access all basic functions of the Device Manager.

However, provisioning or updating large numbers of devices can be a lot of work if done through the web interface. For this purpose we provide you with the Device Manager API.

To use the Device Manager API you need an account to KPN Thingpark. You will only have this if you are a KPN LoRa-only customer.

Getting started

The starter documentation of the Device Manager API can be found following the link below. All API calls you need for managing your device can be found in this postman collection. If you want to do more using the API, please read on at the bottom of this page at Going further.

Setting up Postman

  1. If you do not have Postman installed, do so from here.

  2. Open the documentation using the link above and click on the Run in Postman button in the top right of the page. This will open the collection in Postman.

  3. Create a new Environment in Postman and use that environment. The post-request scripts will be storing intermediate values here. Learn more on environments here.

Setting up another client

When using another API client or when you are writing your own scripts using the Device Manager API, make sure of the following things:

  • The base URL for all API calls is https://www.kpn-lora.com/thingpark/wireless/rest.

  • Enable cookies on all API calls, else the session on the API side will not stick.

Quick start

The following steps allow you to authenticate yourself to the API, get some data using an API call and log out again.

Login

With this request you use your credentials to obtain an access code to access the Device Manager API. Fill in the email address and password of your Thingpark Subscription Account in the corresponding body parameters in the request and send the request.

The response of the login API call will be HTML and it will be as following:

<!DOCTYPE html>
<html lang="en">
<head>...</head>
<body class="container">
<!-- information from the server to the client -->
<div id="serverInfo" style="display:none">
<!-- error messages -->
<span id='errorCode'>{{ON_ERROR_HERE_IS_AN_ERROR_CODE}}</span>
<span id="info1"></span>
<span id="info2"></span>
<!-- uri to redirect to -->
<span id='redirectURI'>https://www.kpn-lora.com/deviceManager/?userAccessCode={{HERE_WILL_BE_YOUR_ACCESS_CODE}}&gmaps=</span>
</div>
...
</body>
</html>

You need to check two parts in the response body. The errorCode-span will contain an error code when there is an error. The following error codes can occur:

Error codes

Description

50, 108, 109, 123

Wrong login or password. Please retry

121

The account has been locked

124

The account is not associated with this application.

The redirectURI-span will contain an URI when you successfully logged in. You should take the userAccessCodeattribute from the URI.

The Postman example contains an after-request test that will interpret the error code for you. Also when successfully logged in, the test will store the userAccessCode you in your Postman Environment.

After obtaining the userAccessCode, you need to start the API session using another API call. The result of the Start session API call will give you the sessionToken and subscription values that you need for all other API calls.

The Postman example stores these values in your Postman Environment.

Get subscriber information and other calls

After you obtained the sessionToken and subscription values from the previous API call you can do all data API calls in the Device Manager API. This API call, for instance, returns you the information of your subscriber.

After executing all API calls you want, you can close the session with this API call. It will render your sessionToken invalid.

More information

Base URL

https://www.kpn-lora.com/thingpark/wireless/rest

Data types

All examples are in JSON, but the API will also support XML as data type. Set the Accept header to one of the following values as you wish:

Data type

Header value

JSON

application/json

XML

application/xml

Going further

Additional information on all available API calls in the Device Manager API can be found here:

The complete Device Manager API documentation

Disclaimer

The current Device Manager API is part of the so called OSS-API which is not part of our current Service Level Agreement. This means functionality can change without notice. Soon the KPN Things API's will provide you with means to provision your LoRa device through serviced API's.