Skip to main content
Version: 1.0

KONA Core REST API

Overview​

Use the REST API of TEKTELIC KONA Core Network Server to read and manage your LoRaWAN® network from your own system. In this guide you sign in, send your first request, page through a list of devices and refresh your token. Every operation is listed in the sidebar of this reference, grouped by entity. Each operation page names its group and path.

The REST API is for managing the network: gateways, applications, devices and users. To receive device data as it arrives, use an integration instead. See Integrations Overview.

Before you start​

  • A KONA Core user account. The API acts with the role of that account. See Users, Roles & Permissions. confirm that each role has the same permissions in the API as in the UI.
  • We recommend a separate user account for each system that calls the API, with the lowest role it needs. Then you can disable one system's access without affecting people who use the UI.
  • curl on the command line, or any HTTP client. The examples use curl.
  • The server of your region:
RegionServerSwagger UI
Europe (EU)lorawan-ns-eu.tektelic.comOpen
North America (NA)lorawan-ns-na.tektelic.comOpen

Use the region where your account was created. For an on-premises installation, ask your administrator for the KONA Core base address.

Steps​

Sign in​

  1. Send your email and password to POST /api/auth/login:

    curl -X POST https://lorawan-ns-eu.tektelic.com/api/auth/login \
      -H "Content-Type: application/json" \
      -d '\{"username": "<email&gt;", "password": "<password&gt;"\}'

  2. Keep both values from the response:

    \{
      "token": "<access-token&gt;",
      "refreshToken": "&lt;refresh-token&gt;"
    \}

    The access token is valid for 2 hours and the refresh token for 24 hours. Use the access token for requests and the refresh token to obtain a new token pair when needed.

Store the tokens and the password as secrets. Don't put them in source code or logs.

Send your first request​

  1. Send a request with the access token in the X-Authorization header. This example lists the applications of your Customer:

    curl https://lorawan-ns-eu.tektelic.com/api/customer/applications \
      -H "X-Authorization: Bearer <access-token&gt;"

  2. The response is a JSON array with one object per application. Each object has an id, a name and a devicesCount, among other fields:

    [
      \{
        "id": \{"entityType": "APPLICATION", "id": "<application-id&gt;"\},
        "name": "<application-name&gt;",
        "devicesCount": 12
      \}
    ]

To read the same list for other levels, see Get customer applications and the other operations in the API Reference.

Page through a list​

Operations that return many entities take limit and page parameters. page starts at 0.

  1. Request the first page of devices in an application:

    curl "https://lorawan-ns-eu.tektelic.com/api/application/<application-id&gt;/devices?limit=50&page=0" \
      -H "X-Authorization: Bearer <access-token&gt;"

  2. The response has the total count and the current page:

    \{
      "totalElements": 120,
      "data": [
        \{"name": "&lt;device-name&gt;", "deviceEUI": "&lt;DevEUI&gt;", "deviceClass": "&lt;device-class&gt;", "active": true\}
      ]
    \}

  3. Increase page until you have read totalElements entities.

Device objects include the device's keys, such as appKey, nwkSKey and appSKey. Treat API responses with devices as secrets. See Security & Keys. For all parameters, such as filters and sorting, see Get application devices. confirm the maximum value of limit.

Refresh the token​

  1. Before the access token expires, send the refresh token to POST /api/auth/token:

    curl -X POST https://lorawan-ns-eu.tektelic.com/api/auth/token \
      -H "Content-Type: application/json" \
      -d '\{"refreshToken": "&lt;refresh-token&gt;"\}'

  2. Replace both stored tokens with the new token and refreshToken from the response.

When the refresh token expires too, sign in again. We recommend refreshing when the access token is a few minutes from expiry, rather than after a request fails.

Try requests in the Swagger UI​

You can also send requests from your browser in the Swagger UI of your region: Europe (EU) or North America (NA).

  1. Sign in with POST /api/auth/login as above, and copy the access token.
  2. In the Swagger UI, select Authorize.
  3. Enter Bearer <access-token> and select Authorize.
  4. Find the operation by its group and path. Each operation page of this reference names both.

Swagger UI with the Authorize dialog.

warning

Requests from the Swagger UI change real data in your account, the same way as the UI does. Test write operations on test entities first.

Check the result​

Your first request returns HTTP status 200 and a JSON array of your applications. If the array is empty, your account has no applications yet, or your role can't see them.

Troubleshooting​

SymptomLikely causeWhat to do
Sign-in returns 401 with "message": "Authentication failed" and "errorCode": 10Wrong email or password, or the account isn't activatedSign in to the UI with the same account to check it. Use the server of your region.
A request returns 401 with "error": "Unauthorized"The X-Authorization header is missing, or the token isn't validAdd the header, with the word Bearer and a space before the token. If the header is there, sign in again to get a new token.
A request returns 500 with "error": "Internal Server Error"The header value isn't a token at all, for example it was pasted incompletelyCopy the whole token value again, or sign in again. confirm the status that KONA Core returns for an expired access token.

Still stuck? A Sub-Customer contacts their Customer, a Customer contacts their Provider, and a Provider contacts TEKTELIC Support. Send the request (method and path, without the token), the time in UTC, the HTTP status and the response body.

Authentication​

Security Scheme Type:

apiKey

Header parameter name:

X-Authorization

Contact

TEKTELIC Communications Inc.:

URL: https://www.tektelic.com/