Introduction

The IoT Programmable SIM API allows you to build smart cellular-based IoT applications. The API actually consist of a family of APIs that you can use to customize cellular network resources to adapt to any IoT use case. These APIs connect all devices to the JpU HyperCore platform.

For example:

  • Activate and deactivate IoT SIM cards on demand.
  • Isolate and customize communication between IoT devices with vLANs.
  • Create IPSec tunnels for security.
  • Restrict access with firewall rules.
  • Ensure delivery to specific devides with IoT/M2M secured SMS.


API specification

Test the API on SwaggerHub


Base URL

https://api-prd.kpn.com/iot/jpu/iotprogrammablesim


Conceptual model

Conceptual model

IoT conceptual model

Definitions


Definitions

The IoT Programmable SIM API use the Internet of Things terminology. It refers to a SIM card as a 'Thing' and to a group of SIM cards sharing the same network configuration as a 'Things Group'. Below are the definitions of the main terms that you need to understand to use the API.

APN

An Access Point (APN) is a gateway between a GSM, GPRS, 3G or 4G mobile network and another computer network, such as the public internet.

IP Profile

The 'IP Profile' is a private network-based firewall module that can be used to protect the IoT devices in the from undesired incoming traffic or restrict access from the devices to specific network destinations.

IPSec VPN

Internet Protocol Security (IPsec) VPN refers to the process of creating and managing VPN connections or services using an IPsec protocol suite. It is a secure means of creating VPN that adds IPsec bundled security features to VPN network packets.

NAT

Network Address Translation (NAT) is a method of remapping one IP address space into another by modifying network address information into Intenet Protocol (IP) datagram packet headers while they are in transit accross a traffic routing device.

Network

A 'Network' is a virtual local network with one or more IP address pools. These pools are assigned to Things when connecting to the network. The Network also includes a routing table used to determine the network routes to external entities. You can define independent NAT port forwarding rules and IPSec VPN tunnels within each Network.

Thing

A 'Thing' represents a SIM card or a device with a SIM card, thus an entity that has internet connectivity through a cellular network. The 'Thing' has many properties that you can use to retrieve detailed network information related to a specific SIM card and configure settings.

Things Group

A 'Things Group' is an entity that allows to tie together all the configuration profiles that define an IoT use case. With this input, the same configuration profiles are easily applied to all the 'Things' in the 'Things Group'.


API workflow

API WorkFlow


Features and constraints

By default, upon shipping, all your Things are provisioned in a default Things Group. The default Things Group is in itself provisioned with a default IP pool, Network and IP profile, to make it easy for you to get started. Although, to avoid preliminary charges, the Things are set to the state of 'PROVISIONED'. Before you can start using the IoT Programmable SIM card, the state needs to be set to 'ACTIVE'.

The default configuration of the firewall is empty, meaning all traffic in the inbound and outbound chain is allowed by default, similarly to any traditional mobile data service. If your IoT device does not recognize the APN automatically, find the APN name in the Network profile. The Things are all configured by default to get an IP address dynamically from the Network IP pool. At the initial stage, the Network profile does not include any NAT or VPN configuration.

Features

  • Isolating use cases with multiple networks: Use this feature to isolate use cases that need different levels of security or network configurations, like IPSec VPNs or different firewall rules. For this you need to create a multitude of Things Groups, Networks and IP Profiles and distribute the Things across different Things Groups.
  • Isolating Things within a network: Use this feature to prevent potential malware from moving from one IoT device to another. Things will only be able to communicate with the back-end application.
  • Restricting mobile services for Things: Use this feature to eliminate potential vulnerabilities by restricting mobile services for specific Things to data or SMS services, for example.
  • Monitoring physical SIM location: Use this feature to identify potentitial physical threats to IoT devices by monitoring changes in SIM card IMEI parameters in the Thing attributes. The IMEI parameters are updated each time the SIM card is used by the IoT device.
  • Locking IP addresses: Use this feature to lock an IP address to a Thing when using NAT port forwarding rules. This way the lease time of this IP addresses will never expire and the Thing will always have the same IP address.
  • Retrieving billing reports: Use this feature to retrieve mobile services charges for your whole account, or specific Things or Things Groups within your account. The report show what your account will be charged at the end of the billing cycle per MB or per SMS.
  • Reporting lost or damaged SIM cards: Use this feature to update the status of your Things. When a SIM is permanently out of service, stop charges to this SIM by setting the status of the Thing to 'RETIRED'. When a SIM card is out of service temporarily, change the Thing state to 'SUSPENDED'. It needs to be set to SUSPENDED during the entire billing cycle to be dismissed from charges.
  • Creating users for your account: Use this feature to create additional users within a same account. Choose the right permission level from the pre-defined settings to grant partial or complete access to the API.
  • Performing bulk actions: Use this feature to invoke the API to perform an action on several Things at once, such as activating all SIM cards. If you are using multiple Things Groups and want to perform and action to many Things across several Things Groups, assign tags to the Things and use the tags to apply bulk actions.

Constraints

  • Account access constraints: A user with administrator rights can create more users for a single account, but it is currently not possible for to create a second account for a user or to create sub-accounts.
  • Mobile services constraints: The mobile services provided by the IoT programmable SIM cards enable the consumption of cellular data and exchange of M2M SMS commands. Since the IoT programmable SIM card is not equiped with an addressable mobile phone number, it is not possible to receive phone calls or short messages from a foreign landline or mobile phone. If you require an addressable phone number, you can create a virtual phone number with Vonage's Phone Number API and assign it to your Things.
  • IP address and IP pool constraints: Your account is pre-configured with one or more IP pools. Each IP pool has a limited amount of IP addresses which are dynamically assigned to the IoT programmable SIM cards that consume data services. If you use multiple Networks, you might reach a limitat when resizing the IP pools. If this is the case, please contact us to request IP pool extensions.
  • APN selection constraints: Your account is loaded with a fixed shared APN which is fragmented to ensure a complete segregation of data between accounts. It is currently not possible to assign or request a different APN. If your IoT device does not automatically detect the serving APN, retrieve the APN name using the Network API.
  • Roaming and coverage constraints: The IoT programmable SIM card can use mobile services in the Netherlands, Belgium and Luxembourg on any of the following network generations: 2G, 3G, 4G, LTE-M. Support of NB-IoT is planned in the future but not yet available on this service.


Getting started

Make sure you've read What's in it for you for more info on how to register and start testing APIs.

Authentication

The API follows the KPN Store API Authentication Standard to secure the API. It includes the use of OAuth 2.0 client_id and client_secret to receive an access token.

Go to the Authentication tab on top of this page to find out how to:

  • Authenticate to an API using cURL.
  • Authenticate to an API on Swaggerhub.
  • Import Open API Specifications (OAS), also called Swagger files into Postman.


How to...

Retrieve initial information

Sequence diagram #1

Activate a new IoT SIM card

Sequence diagram #2

Add a firewall filter rule

Sequence diagram #3

Add a NAT port forwarding rule

Sequence diagram #4

Set up an IPSec tunnel for end-to-end encryption

Sequence diagram #5

Send an SMS command to a Thing

Sequence diagram #6


Return codes

Code Description
200 Success.
201 Created.
202 Accepted.
302 Found. Link in location header.
400 Bad request.
401 Unauthorized.
403 Forbidden.
404 Not found.
405 Method not allowed.
412 Precondition failed.
429 Too many requests.
500 Internal server error.
502 Bad gateway.
503 Service unavailable.


HTTP response headers

The following tables display the standard response headers that are returned with each API response:

Standard response field name Description
sunset This field will be populated with the deprecation details. By default the value is n/a.
api-version Indicates the API version you have used.
quota-interval Used to specify an integer (for example, 1, 2, 5, 60, and so on) that will be paired with the quota-time-unit you specify (minute, hour, day, week, or month) to determine a time period during which the quota use is calculated.
For example, an interval of 24 with a quota-time-unit of hour means that the quota will be calculated over the course of 24 hours.
quota-limit Number of API calls an user can make within a given time period.
If this limit is exceeded, the user will be throttled and API requests will fail.
quota-reset-UTC All quota times are set to the Coordinated Universal Time (UTC) time zone.
quota-time-unit Used to specify the unit of time applicable to the quota.
For example, an interval of 24 with a quota-time-unit of hour means that the quota will be calculated over the course of 24 hours.
quota-used Number of API calls made within the quota.
strict-transport-security The HTTP Strict-Transport-Security (HSTS) response header lets a website tell browsers that it should only be accessed using HTTPS, instead of using HTTP. All present and future subdomains will be HTTPS for a maximum of 1 year and access is blocked to pages or sub domains that can only be served over HTTP including HSTS preload lists of web browsers.
Strict-Transport-Security: max-age=31536000; includeSubDomains; preload.
Access control field name Description
access-control-allow-credentials Tells browsers whether to expose the response to frontend JavaScript when the request's credentials mode (Request.credentials) is include.
When a request's credentials mode (Request.credentials) is include, browsers will only expose the response to frontend JavaScript if the Access-Control-Allow-Credentials value is true. Boolean.
access-control-allow-origin Indicates whether the response can be shared with requesting code from the given origin.
access-control-allow-headers Used in response to a pre-flight request which includes the Access-Control-Request-Headers to indicate which HTTP headers can be used during the actual request.
access-control-max-age Indicates how long the results of a pre-flight request (that is the information contained in the Access-Control-Allow-Methods and Access-Control-Allow-Headers headers) can be cached.
access-control-allow-methods Indicates which HTTP methods are allowed on a particular endpoint for cross-origin requests.
For example: GET, PUT, POST, DELETE.
content-length The Content-Length entity header indicates the size of the entity-body, in bytes, sent to the recipient.
content-type The Content-Type entity header the client what the content type of the returned content actually is.

Mopinion feedback