LogoLogo
  • KPN THINGS USER GUIDE
    • Introduction
    • Getting started
      • Registration and setup
      • Device simulator app
      • Connect devices
        • SIM cards
        • Supported devices and KPN Devices
        • SODAQ R412M
        • Smartrak
        • Marvin development board
        • LoPy5
        • Arduino MKR WAN 1300/1310
        • Arduin MKR NB 1500
    • All videos
    • Tutorials
      • Configure a flow
      • Connect a HTTPs destination
      • Create a simple IoT web applicationPage
      • Send instruction to LoRa DevicePage
      • Send your data to Azure SQL
      • Technical overview
        • Management data model
        • Uplink communication
        • Downlink communication
        • Location data
      • Accounts and projects
        • Customer accounts and users
        • Projects
        • Customer management
        • Cost overview and contract
    • Frequently asked
      • Multi Factor Authentication
  • GENERAL FUNCTIONS
    • Quick reference videos
    • APIs
  • THE PORTAL EXPLAINED
    • Things Manager
      • Devices
        • Bulk operations
      • Data
        • Device data graph
      • Connectivity
        • LoRa connectivity configuration
      • Bulk reports
    • Things Creator
    • Support
      • News
      • Release notes
      • Real-time status
      • Service reports
      • Documents
      • Support tickets
      • Invoices
      • Contact info
    • Shop
  • BUILDING BLOCKS
    • Devices
      • Sensors
        • KPN Conditionsensor CO2 II
        • KPN Conditionsensor CO2 III
        • KPN Conditionsensor CO2 III motionPage 1
        • KPN FillTag I
        • KPN FillTag II
        • 1M2M ED1608
        • Elsys ERS
        • Device Simulator (Mobile Phone app)
        • Generic Device (Internet connected)
        • Generic LoRa device (preset connectivity)
        • Generic LoRa device (programmable)
        • Generic M2M device
        • Generic M2M device (with Internet connection)
      • Trackers
        • KPN Global Tracker Autonomous
        • KPN Global Tracker Wired
        • KPN LocationTag I
        • KPN LocationTag II
        • KPN LocationTag II v2
        • KPN LocationTag II v2 Expert Mode
        • KPN LocationTag II v3
        • KPN LocationTag III (with GPS)
        • KPN LocationTag III (without GPS)
        • KPN LocationTag III v2
        • KPN LocationTag III v2 Buffer
        • KPN LocationTag III v3
        • KPN LocationTag III v4
        • KPN LocationTag V
        • KPN LocationTag VI
        • KPN LocationTag WS
        • Streamline LoRa
        • Streamline M2M
        • Viloc
      • Routers
      • Gateways
        • KPN FSK Basestation
      • Device SDK
    • Connectivity
      • Connecting LoRa devices
        • LoRa connectivity configuration
      • Connecting M2M devices
      • Connecting Internet devices
      • Connecting MQTT Devices
    • Data Processing
      • ThingsML and SenML
        • ThingsML
        • SenML
          • Understanding and Interpreting SenML Data
          • Changes in KPN SenML
      • Device Twin
      • Decoders and encoders
        • Common measurements list
        • Decoder migrations
        • DIY Decoder
          • DIY decoder scripts
      • Merger
      • Device data
      • Devices
    • Destinations
      • HTTPS destination
      • MQTT broker
      • Cumulocity IoT Platform
      • Azure Event Hubs
      • Azure IoT Hub
      • Test Endpoint
      • ThingsBoard
      • Datacake
      • AWS Lambda
      • Google Cloud Run functions
  • IOT LINE UP
    • Freemium
      • Test SIM cards
    • Explorer
    • Modular
    • Tailored
    • Terms and Conditions
Powered by GitBook

© 2024 KPN - All rights reserved.

On this page
  • How Things API access works
  • The API Key
  • The access token
  • Getting started
  • 1. Find your GRIP Tenant ID in the Things Portal
  • 2. Create your API Key and API Key's Secret in GRIP
  • Perform Things API calls
  • Request access token through GRIP API
  • List devices
  • Send downlink to device
  • Full documentation of KPN Things APIs
  • Postman API Collection
  • API access to customer environments as a reseller
  • ⚠️Deprecated: performing API call in sub-customer environment
  • ⚠️Deprecated: request access rights to a sub-customer
  • SSL certificate information

Was this helpful?

Export as PDF
  1. GENERAL FUNCTIONS

You can use API access to KPN Things for instance to automate some actions you normally do manually through the KPN Things Portal

PreviousQuick reference videosNextThings Manager

Last updated 27 days ago

Was this helpful?

2.3. Give new API Key access to KPN Things

You need to give your newly created API Key access to the KPN Things service before you can use it. For this, click on Services and roles (#1 in the screenshot), and click on Add a service (#2 in the screenshot).

✨ Early access feature! API access to KPN Things is currently in beta! We try to notify users in advance about breaking changes, but we cannot guarantee continuity of this service just yet.

How Things API access works

The API Key

To access the KPN Things APIs you need an API Key. And these API Keys are managed by GRIP, the identify management platform of KPN. Your user account used to access the KPN Things Portal is also managed by GRIP. Learn more about .

In GRIP there are API Keys. These are separate entities in a tenant (a customer environment). That means an API Key is not user bound, but it is rather a separate entity.

The access token

Each time you want to access the KPN Things APIs, you need to request an access token from the GRIP API using your API Key. This access token you get is valid for one hour, and can be used as a bearer token to access KPN Things APIs directly.

That means, for each API call you do to KPN Things, you need to add the following Authorization header:

Authorization: Bearer {accessToken}

There is no refresh token. To regain access after your access token has expired, just request another access token through the GRIP API.

You can find more information about the access method we employ here on the Grip Knowledge Base website, linked below. The method is called Machine authentication.

Getting started

This is a step-by-step explanation to find all required information needed for requesting an access token from GRIP.

Value

Description

GRIP Tenant ID

The unique identifier of your GRIP environment.

Application ID

The ID of the service you want to access, being KPN Things. Used as audience in your client credentials request.

For KPN Things it is this: 4dc82561-f65f-523g-dek9-6c79ec314f02

Client ID

The API Key's ID

Client Secret

The API Key's Secret key

1. Find your GRIP Tenant ID in the Things Portal

2. Create your API Key and API Key's Secret in GRIP

It is best practice to create individual API Keys for each instance that will access the KPN Things APIs.

Log into the GRIP Portal as an administrator.

  • If you have a KPN Developer account, you will be an administrator in the GRIP Portal.

  • If you have a MijnKPN Zakelijk account, you should ask your local administrator for access.

2.1. Go to API Key management

To create API Keys, you need to be an administrator in the GRIP Portal.

Then, open the Admin panel using the role drop down (#1 in the screenshot), click on Identity in the side menu (#2 in the screenshot) and click on API keys (#3 in the screenshot). This brings you to the API Key management page. Now, click Add to add a new API Key (#4 in the screenshot).

2.2. Create new API Key

In the following pop-up, give your new API Key a Display name and a Description. Then click Add to create your new API Key.

2.3. Give new API Key access to KPN Things

You need to give your newly created API Key access to the KPN Things service before you can use it. Click on Services and roles (#1 in the screenshot), and click on Add a service (#2 in the screenshot).

A modal will open. Click on the checkbox next to KPN Things (#1 in the screenshot) and hit Add (#2 in the screenshot).

Click on the KPN Things service and select the desired role and access level for your API key:

Then, click Save to finally give your API Key access to KPN Things.

2.4. Fetch credentials of new API Key

Now, when you click back on General information, you will see the ID and Secret key of your new API Key.

Perform Things API calls

Request access token through GRIP API

POST https://auth.grip-on-it.com/v2/{tenantId}/oidc/idp/c1/token

With this request, you obtain the access token you use to access the KPN Things API's.

Headers

Name
Type
Description

Content-Type

string

application/json; charset=utf-8

Request Body

Name
Type
Description

grant_type

string

client_credentials

audience

string

The Application ID (see above)

client_id

string

The API Key's ID

client_secret

string

The API Key's Secret key

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Error

Solution

Feature user does not exist anymore.

You should check your API Key ID or Secret, they may be incorrect.

Feature service does not exist anymore.

You should add the KPN Things Portal service to your API Key through the GRIP Portal.

SAML request error: "idpId" not found.

Your tenantId (which is a path variable) is incorrect.

List devices

GET https://api.kpnthings.com/api/devices

Now you have an access token, execute the following call to list your Devices

Query Parameters

Name
Type
Description

currentPage

number

0

pageSize

number

20

search

string

(case sensitive partial string search)

sortBy

string

name

sortOrder

string

ASC

Headers

Name
Type
Description

Authorization

string

Bearer {accessToken}

Accept

string

application/vnd.kpnthings.device.v1.response+json

{
    "content": [
        {
            "uuid": "xxxxxx",
            "name": "My first own device",
            "description": "",
            "metadata": null,
            "deviceSpecificationUUID": "d2723e99-1fe4-4d60-9b6d-8061f7414b24",
            "barcode": null
        },
        ...
    ],
    "last": true,
    "totalPages": 1,
    "totalElements": 2,
    "sort": [
        {
            "direction": "ASC",
            "property": "name",
            "ignoreCase": false,
            "nullHandling": "NATIVE",
            "ascending": true,
            "descending": false
        }
    ],
    "first": true,
    "numberOfElements": 2,
    "size": 20,
    "number": 0
}

Response codes

Code

Description

🟢 200 OK

Your request was correct.

🟢 201 Created

You created an object with your request.

🟢 204 No Content

Your request was correct, but there is no information to return, for instance after deleting an object.

🟡 302 Found

Your access token is incorrect or does not have access to KPN Things. Please check your API Key in GRIP.

🔴 400 Bad Request

Something in your request is not correctly formatted. For instance your body structure, your accept header or a query parameter.

🔴 403 Forbidden

Your access token is correct, but you do not have the authorization to access that resource.

Send downlink to device

POST https://api.kpnthings.com/api/actuator/downlinks

Body: [{"bn":"urn:dev:DEVEUI:{devEUI}:", "n":"payloadHex", "vs": "{payload}"}]

Query Parameters

Name
Type
Description

externalReference

string

Optional reference for you to choose

port

integer

LoRa FPort to send data on

Headers

Name
Type
Description

Accept

string

application/vnd.kpnthings.actuator.v1.response+json

Content-Type

string

application/json

Full documentation of KPN Things APIs

Postman API Collection

Postman environment variables

Variable

Value

gripBaseUrl

https://auth.grip-on-it.com

tenantId

Your grip tenant id

applicationId

4dc82561-f65f-523g-dek9-6c79ec314f02

keyId

Your key id

keySecret

Your key secret

baseUrl

https://api.kpnthings.com

API access to customer environments as a reseller

When you are a reseller of KPN Things, you can manage the KPN Things environments of your own customers on their behalf using the KPN Things APIs. To do so, you should indicate which API calls are meant to operate within the context of a specific customer by specifying the KPN-Things-Security-Context header:

KPN-Things-Security-Context: client:uuid:{{customerID}}

The value of {{customerID}} is the UUID identifying the customer for whom you intend to manage their KPN Things environment.

When you specify the KPN-Things-Security-Context header, KPN Things will validate the syntax and check that your own account is a reseller of the given {{customerID}}. If either check fails, your API call will be denied. Note that you can specify only a single KPN-Things-Security-Context header for each API call: multiple values are not supported.

💎 Add-on feature

⚠️Deprecated: performing API call in sub-customer environment

If you have Customer Management in your account, you can manage Things accounts for your own customers. These customers of you, let's call them sub-customers, have their own customer account in KPN Things. But you have access rights with your API Key to perform actions in their account.

The principle

To perform an API call in a sub-customer environment, there are two requirements:

  1. You should have requested the access rights to the individual sub-customer environment

  2. For all API calls you perform, you should add the following HTTP header:

x-client-id: {{customerID}}

Step 1: Request access rights

This only has to be one once per API Key per sub-customer.

  1. Perform the Request KPN Things access token through GRIP API call.

  2. Perform the following API call:

⚠️Deprecated: request access rights to a sub-customer

GET https://api.kpnthings.com/api/v1/lifecycle/clients/:clientId/context-switch

Path Parameters

Name
Type
Description

clientId

string

Customer ID of your sub-customer

Headers

Name
Type
Description

Content-Type

string

application/json

Accept

string

application/json

Step 2: Perform API call in sub-customer environment

Now you have access rights to the sub-customer environment with your API key. Now you can perform any API call you have the rights for in the sub-customer environment by simply adding the x-client-id header to the API call when you execute it.

SSL certificate information

If required for your security implementation, all certificate files of the chain can be downloaded here:

In the KPN Things Portal, visit the by clicking on your name in the top right and then clicking "Customer Details" in the overflow menu. On the following page, you will find your GRIP Tenant ID.

Learn more about .

Don't want to manually implement the API calls? Use our published to quickly generate code snippets for all published API calls!

More information in the .

Currently the APIs of KPN Things are documented using Postman. is an easy to use API development tool.

To get the Postman collection working, you need to create a with the following variables:

To get started as a reseller and set up environments for customers of your own within KPN Things, you require the add-on feature.

This API is deprecated: .

💎 Add-on feature This feature is only available if you have the add-on feature .

Find the Customer ID from the sub-customer you want to perform an action on. You can use the All Customers page to search in your Customers and then open the of the concerning Customer to find its Customer ID.

This API is deprecated: .

The SSL server certificates of KPN Things and GRIP are provided by the new PKI Overheid CA hierarchy. On kpn.com you can .

Root:

Intermediate:

Intermediate:

Customer detail page
GRIP Knowledge Base (documentation)
Postman
Postman environment
Customer Management
Customer Management
Customer details page
learn more about the KPN certificates
Staat der Nederlanden EV Root CA
Staat der Nederlanden Domein Server CA 2020
KPN PKIoverheid Server CA 2020
the account you use to access KPN Things
Postman collection
use the KPN-Things-Security-Contextheader instead
use the KPN-Things-Security-Contextheader instead
the account you use to access KPN Things
KPN Grip | Identity management by KPN
Grip
https://www.getpostman.com/collections/46072fa86a8844c3d63ewww.getpostman.com
Page cover image