API access ✨
You can use API access to KPN Things for instance to automate some actions you normally do manually through the KPN Things Portal.
Last updated
You can use API access to KPN Things for instance to automate some actions you normally do manually through the KPN Things Portal.
Last updated
✨ 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.
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 the account you use to access KPN Things.
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.
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 to to KPN Things. you need to add the following Authorization header:
There is no refresh token. To regain access after the validity of 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.
You will need the following four values to be able to request an access token from GRIP:
In the KPN Things Portal, visit the Customer detail page 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.
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 administrator.
If you have a KPN Developer account, you will be administrator in the GRIP Portal.
If you have a MijnKPN Zakelijk account, you should ask your local administrator for access.
Learn more about the account you use to access KPN Things.
To be able 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).
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.
You need to give your newly created API Key access to the KPN Things Portal 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).
A modal will open. Click on the checkbox next to KPN Things Portal (#1 in the screenshot) and hit Add (#2 in the screenshot).
Then, click Save to finally give your API Key access to KPN Things.
Now, when you click back on General information, you will see the ID and Secret key of your new API Key.
Don't want to manually implement the API calls? Use our published Postman collection to quickly generate code snippets for all published API calls!
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 APIs.
More information in the GRIP Knowledge Base (documentation).
GET
https://api.kpnthings.com/api/devices
Now you have an access token, execute the following call to list your Devices
POST
https://api.kpnthings.com/api/actuator/downlinks
Body: [{"bn":"urn:dev:DEVEUI:{devEUI}:", "n":"payloadHex", "vs": "{payload}"}]
Currently the APIs of KPN Things are documented using Postman. Postman is an easy to use API development tool.
To get the Postman collection working, you need to create a Postman environment with the following variables:
💎 Add-on feature This feature is only available if you have the add-on feature Customer Management.
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.
To perform an API call in a sub-customer environment, there are two requirements:
You should have requested the access rights to the individual sub-customer environment
For all API calls you perform, you should add the following HTTP header:
This only has to be one once per API Key per sub-customer.
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 Customer details page of the concerning Customer to find its Customer ID.
Perform the Request KPN Things access token through GRIP API call.
Perform the following API call:
GET
https://api.kpnthings.com/api/v1/lifecycle/clients/:clientId/context-switch
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.
The SSL server certificates of KPN Things and GRIP are provided by the new PKI Overheid CA hierarchy. On kpn.com you can learn more about the KPN certificates.
If required for your security implementation, all certificate files of the chain can be downloaded here:
Intermediate: Staat der Nederlanden Domein Server CA 2020
Intermediate: KPN PKIoverheid Server CA 2020
Name | Type | Description |
---|---|---|
Name | Type | Description |
---|---|---|
Name | Type | Description |
---|---|---|
Name | Type | Description |
---|---|---|
Name | Type | Description |
---|---|---|
Name | Type | Description |
---|---|---|
Name | Type | Description |
---|---|---|
Name | Type | Description |
---|---|---|
Value
Description
Tenant ID
The unique identifier of your GRIP environment. Follow step 1 in the getting started to find it in the Things Portal.
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 you get from step 2 of the getting started.
Client Secret
The API Key's Secret key you get from step 2 of the getting started.
Content-Type
string
application/json; charset=utf-8
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
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.
currentPage
number
0
pageSize
number
20
search
string
(case sensitive partial string search)
sortBy
string
name
sortOrder
string
ASC
Authorization
string
Bearer {accessToken}
Accept
string
application/vnd.kpnthings.device.v1.response+json
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.