API Blog Series Part 2: Auto-provisioning Over API

API Blog Series Part 2: Auto-provisioning over API

EMnify’s purpose-built RESTful API enables you to integrate your existing business systems and applications with our connectivity management platform. It is a powerful resource for controlling, management and deploying your IoT & M2M products and services.

Following the introduction of our API Blog Series which gave a detailed overview of the EMnify API, we want to dig deeper into the technical integration possibilities and benefits. In this part of the blog series, Automated Provisioning over API, we will explore how to configure protocols to automatically initiate and configure  your IoT & M2M devices or services.

 

What is Auto-provisioning?

Automated provisioning (or auto-provisioning) is the ability to deploy a technology or service using protocols that are carried out electronically, and without the need for manual input. In the cellular IoT & M2M context, it specifically means managing the lifecycle of a SIM, which connects your product or service to the Internet of Things. This is best done over an API, which allows you to build the systems and process for automation that work best for your business needs.

On the EMnify platform, auto-provisioning includes the automation of ordering SIMs, activation and deactivation of SIMs, connectivity testing, device configuration, tariff limit implementation, and SIM decommissioning. Practically, these actions can standardize how the SIMs arrive at a factory for installation, how the SIM is tested, and how the SIM is activated by the end user.

Auto-provisioning is most important for the scalability of IoT & M2M products and services. When a project includes hundreds, thousands or even millions of devices that need to be connected to a mobile network, it is impossible to manually configure each SIM in each device. With the right automation protocols in place, a business becomes agile and scalable with minimal time and resources.

 

Endpoint and SIM Lifecycle Management

Cellular IoT & M2M use cases often involve a high number of devices that need to be connected to a mobile network. For this to happen, devices must first be fitted with a SIM and network connectivity must be provisioned. Efficiency is key in the technology industry, and automation can be enabled for each of the essential processes of the SIM lifecycle.

In general, the process of a SIM lifecycle include:

  • Ordering new SIMs in variable quantities: To enable  responsiveness to production pipelines
  • Management of SIM repository: To monitor SIM quantities and statuses
  • On-demand activation and suspension of SIMs: Payment is only necessary when SIMs are active, so temporarily suspending a SIM can save costs. SIMs may also need to be suspended for security reasons.
  • Provisioning of network connectivity and security profiles: For example, setting data limits
  • Automated testing: Quality tests may include SIM activation, SMS or API calls,  status checks, and SIM card suspension
  • Monitoring of network activity: To also monitor costs associated with activities

With the EMnify API, these tasks can be automated from the very beginning of the SIM lifecycle and integrated into existing IT systems.

To expand upon this functionality, we can take a few examples from the lifecycle process, starting with SIM repository management.

 

SIM Repository Management

When it comes to managing a stock of SIMs, the first step is typical to establish a SIM repository. The repository shows which SIMs are available, details their state and gives possible actions that can be applied. Specifically, the repository stores:

  • Which SIMs you have (e..g, form factor), how many SIMs you have, and enables you to retrieve the SIM list
  • The state of the SIM as you provision it (activated/suspended)
  • What details of a SIM you can view and call on-demand

The EMnify API provides integration of this information on-demand.

 

EMnify RestAPI

EMnify provides a RESTful API implementing Javascript Object Notation (JSON) as the primary data format used to create (POST), read (GET), update (PATCH) and delete objects (DELETE). Authentication is implemented by JSON Web Tokens (JWT), while access is either verified by user credentials (for interactive applications) or application tokens. On the EMnify Portal, you can create and revoke application tokens for your different applications as needed.

You can find full API specification and details on authentication procedures here https://cdn.emnify.net/api/doc/EMnify-API-collapsible.html

Examples of API calls are detailed below.

 

Retrieval of SIM List

The entry point “/sim” gives you a list of all your SIM cards in your repository, optional you can filter, sort and retrieve data split into pages by adding additional URL parameters.

GET /api/v1/sim

API SIM Retrieval

 

Retrieval of SIM Details

GET /api/v1/sim/{simId}

Detailed information about a SIM card can be retrieved by adding the ID of the SIM to the API entry point such as “api/v1/sim/789”.

API Retrieval of SIM details

SIM State Management

Once the SIM details are retrieved, management actions can be implemented. One of the most important tasks deals with the machine state and includes which actions you can  perform to activate/suspend SIMs.

The following diagram illustrates the different states:

 

SIM state machine diagram

 

api_call

 

Issued – this SIM card has not been used yet and is available to be activated

Activated – the SIM card is opened for network access and can be used in endpoints

Suspended – the SIM card is temporarily suspended and is blocked from network access, but can be activated again at any time

Terminated – the SIM has been permanently removed from the repository

 

Activate SIM

PATCH /api/v1/sim/{simId}

API Activate SIM

 

Suspending a SIM

PATCH /api/v1/sim/{simId}

API suspending a SIM

 

Auto-discovery of a Device (SIM Association) 

Automated discovery of a device enables you to determine which devices are fitted with which SIMs. This is important during bulk provisioning of IoT devices with embedded SIMs. During device assembly, bulk provisioning may include on-demand activation, automatic testing, and then suspension of the SIM while the device is still in the warehouse. At this time, the SIM and device can be locked together, based on the IMEI of the device, and the SIM will only work with it’s specified device.

In many industries, cellular connected devices are produced and the end user inserts their own SIM into the device. Devices used within the IoT industry regularly require SIMs to be pre-integrated at the factory, before the device is shipped to the end user. Auto-discovery and SIM association ensure that when an end user receives a device with a SIM pre-integrated, they can power on the device and it is ready to use. The information can be used to activate the SIM and register its identity with other systems or applications.

Automation for these steps are as follows:

  1. Once the device with SIM is produced, the first validation is a quality check. When the device is turned on, the SIM ICCID is determined as valid and usable.
  2. Automated connectivity testing occurs next. The device activates, attaches to a network, can optionally send or receive SMS and/or API calls to validate communication, and then deactivates. The device will only reactivate again when it reaches the end user.
  3. Registration of the SIM identity and the cloud service (e.g., the device ID), to determine which SIM is associated with which device.

After these automated processes are completed, the device can be packaged and shipped to a warehouse for storage, or to the end user. When the device reaches the end user, it can be turned on, registered, and will work instantly.

A diagram of this automated process is shown below.

API automated process

 

 

Find SIM in Repository by ICCID

To find a SIM card in the SIM repository by ICCID you can simply filter by the ICCID, this will also work for a list of SIM cards that share the same ICCID prefix:

GET /api/v1/sim?q=iccid:736826736473829773621

API Find SIM in Repository by ICCID

 

Conclusion

Auto-provisioning of SIM cards is an important step in the scalability of IoT. This can only be made possible through the integration of APIs between a business and a service provider. Now that you have a better understanding of some of the ways in which devices can be auto-provisioned, we will continue our blog series with other technical features of the EMnify API, including communication methods such as SMS and USSD, and how to use the power of an API to monetize your product or service. If you missed our first introductory post for this API Blog Series, read it here.

 

Follow us:

twitter-logo transparent-Linkedin-logo-icon

Share this blog post:

Leave A Comment