JpU

IoT Programmable SIM - JpU

JpU

Connect your IoT devices in a secure network

Simple and secure IoT connectivity

  • IoT
  • Network

API reference on SwaggerHub

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.

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 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 Nexmo'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

Authentication

To authenticate you'll need to request an access token. Use your API Store app's credentials (Consumer Key and Consumer Secret) to make an authentication request. The authorization service returns a JSON message that contains the access_token field.

Use one of the following 3 options:

cURL

Execute below cURL command to receive an access token. Replace APP_CONSUMER_KEY and APP_CONSUMER_SECRET with your app's credentials.

curl -X POST \
 'https://api-prd.kpn.com/oauth/client_credential/accesstoken?grant_type=client_credentials' \
 -H 'content-type: application/x-www-form-urlencoded' \
 -d 'client_id=APP_CONSUMER_KEY&client_secret=APP_CONSUMER_SECRET'

If you are using cURL for Windows, please use the command below instead.

curl -X POST "https://api-prd.kpn.com/oauth/client_credential/accesstoken?grant_type=client_credentials" -H "content-type: application/x-www-form-urlencoded" -d "client_id=APP_CONSUMER_KEY&client_secret=APP_CONSUMER_SECRET"

The authentication service returns a JSON message that contains the access token field.

{
    "refresh_token_expires_in": "0",
    "api_product_list": "[xxxxxxx]",
    "api_product_list_json": [
        " xxxxxxx"
    ],
    "organization_name": "kpn",
    "developer_email": "demo123@kpn.com",
    "token_type": "Bearer",
    "issued_at": "1521039195424",
    "client_id": "APP_CONSUMER_KEY",
    "access_token": "haf2SDl07E9N7RluNQ4kJ1TkGgso",
    "application_name": "6e38edxxxxxxxxxxxxxxxx4065d79c",
    "scope": "",
    "expires_in": "3599",
    "refresh_count": "0",
    "status": "approved"
}

SwaggerHub

  1. Click on the Authorize button on the top right.
  2. In the form, fill in client_id and client_secret, using your app's credentials.
  3. Click Authorize.

Postman

When using Postman, you will have to import the Swagger file into a Postman collection as follows:

  1. Open the API reference on SwaggerHub.
  2. On the top right, click Export, click Download API and click 'YAML Unresolved'.
  3. In Postman from the menu click File and click Import... Choose the YAML file you downloaded in the previous step. A new collection will be added.
  4. Select Get Access Token from the collection.
  5. Make sure the right environment is selected, corresponding to the API.
  6. Edit the environment variables client_id and client_secret, using your app's credentials.
  7. Check the response code and message.
  8. Press the Send button to get an access token.

Note: Request variables are no longer linked to an environment, but to the collection.

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