How to use Super SIM eSIM Profiles
Many Internet of Things manufacturers wish to incorporate eSIMs (eUICC SIMs) into their products rather than traditional SIMs in order to take advantage of eSIMs' remote SIM provisioning capabilities. The good news is that they can do so with Super SIM and continue to take full advantage of Super SIM's global connectivity via multiple tier-1 networks.
In fact, working with a virtual Super SIM installed in an eSIM is no different from working with a physical one in card or chip form: you use the same API calls to assign it to a Fleet and manage its state. However, you need to follow a slightly different process to obtain the virtual SIM — called an eSIM profile — and to prepare for its installation on a device.
The Super SIM API provides tools for you to create, or 'reserve', Super SIM eSIM profiles, which are accessible as eSimProfile resources. To make use of the eSIM profiles you have created, you need eUICC (Embedded Universal Integrated Circuit Card) hardware to store them on your IoT device, and Local Profile Assistant (LPA) software, also on the device, to download profiles and manage those installed in the eUICC.
This guide will introduce you to the Super SIM API used to reserve and manage Super SIM eSIM profiles and show you the methods you can apply to install profiles onto devices. If you're new to eSIMs, you may prefer to start with the guide Get Started with Super SIM eSIM Profiles for eUICCs and then return to this longer, more detailed document.
How are eSIM profiles installed?
To use eSIMs, an IoT device needs LPA software. The LPA downloads eSIM profiles from an SM-DP+ (Subscription Manager Data Preparation) server, installs them in the device's eUICC, and manages switching between profiles — the digital equivalent of swapping SIM cards. The LPA may also provide an interface through which users swap the current profile for another to switch between cellular connectivity providers, if that's a choice you as a device manufacturer have chosen to grant them.
There are many ways to implement an LPA. It may be part of a mobile device operating system. For example, many Android devices are already eSIM compatible, and the OS supports the installation of third-party LPAs in addition to its own. If you are building your own IoT hardware, you will need to discuss with your cellular module supplier how to develop and install a suitable LPA. If your choice of eUICC already incorporates an LPA, you will still need to code your application to communicate with it.
The process of installing an eSIM profile goes like this:
You create an eSIM profile on an SM-DP+ server. This is done using the Super SIM API and is typically referred to as "reserving" a profile.
You provide the device's LPA with the address of the SM-DP+ server. There are several methods, discussed shortly, that you can choose from.
The LPA contacts the SM-DP+ server and receives the reserved eSIM profile, which it installs in the device's eUICC.
The SM-DP+ server is an online resource that allows users to download eSIM profiles. It is like a virtual warehouse full of ready-to-use digital SIMs.
Profile installation methods
There are various ways of providing the LPA with the address of the SM-DP+ it should contact. Super SIM supports the following methods:
Activation Code also reserves an eSIM Profile on an SM-DP+ server, but rather than bind the profile to a specific device, a unique identifier called a Matching ID is generated to identify a specific profile that you can claim later. Any device with that ID can claim the eSIM profile, irrespective of its EID. So, when you reserve an eSIM profile, you don't need to know the identity of a target device. Additionally, the SM-DP+ address and matching ID can be combined into a single string to build the Activation Code itself, so the LPA doesn't need to be separately provisioned with this information.
As the Activation Code's value is known before installation, it can be presented in a form that simplifies providing it to the device. A common approach is to supply it as a QR code which can be scanned by devices that include a camera, and the ID and SM-DP+ server address extracted. This makes it ideal as a means to offer eSIM profiles that will be installed by end-users on mobile devices like phones and tablets.
Here is a typical call flow for downloading Super SIM profiles using the Activation Code method:
SM-DP+ Default binds the reserved profile to a specific eSIM which is identified by its eSIM ID (EID). Only that eSIM can then make use of the reserved profile. The LPA sends the host's EID to the server, which responds with the eSIM profile reserved for that EID. When you reserve eSIM profiles with this method in mind, you need to know the identity of the target device.
Here is a typical call flow for downloading Super SIM profiles using the SM-DP+ Default method:
However the LPA gets the address of an SM-DP+ server, when it contacts the server it will receive a profile and install it in the eUICC. Once the eSIM profile has been installed and activated, the host device is able to connect to the Internet.
Let's go through each of these phases in detail.
Prepare an eSIM profile
1. Reserve an eSIM profile
To reserve a profile, you need to send an HTTP POST request containing data appropriate to your chosen installation method to:
This will create a new eSimProfile resource and initiate the process of reserving its linked eSIM profile on the SM-DP+ server.
If you wish to use the Default SM-DP+ method of profile installation, provide the target device's EID as a URL-encoded request parameter. For example, to make the request using curl:
Alternatively, to generate an Activation Code, do not supply an EID but instead set the GenerateMatchingId property to true flag:
Asynchronicity
Reserving an eSIM profile is an asynchronous operation, so the new profile will not be ready to use immediately, though the eSimProfile resource is available straight away. If you're testing the process at the desktop, you can poll the URL provided in the response to your initial request and view the status field of the poll response. When the status is available, the profile is ready for use.
A better approach for server-side code is to provide a callback URL with your initial request.
KORE will issue a GET request to this URL when the eSIM profile is available for download, but you can change it using the CallbackMethod=POST flag.
2. Assign the profile's Sim to a Fleet and activate it
Part of the creation of an eSIM profile is the generation of an associated Sim resource which you use to manage the profile's SIM data. The resource's SID will be included in the poll response as the value of the sim_sid field once the eSimProfile resource's status has become available. At this point, you can also read the SM-DP+ address from the resource's smdp_plus_address field.
If you have asked for a Matching ID to be generated, you can read it now from the same response by extracting the value of the matching_id field.
Use the extracted Sim resource SID assign it to a Fleet resource and to activate it:
Assignment to the Fleet and activation are shown here as a single call, but you may choose to perform these tasks separately and at different points in time, depending on your workflow and use case.
3. Pass the SM-DP+ address to the LPA
This stage will depend on your chosen installation method.
Activation Code
You will have received the Matching ID alongside the SM-DP+ address. The "activation code" is what you get when you combine these values together in the following format:
The $ symbol is a field separator, not a shell variable marker.
Extra formatting may be required depending on how you plan to make the code available. For instance, to use the Activation Code as the basis for a QR code, you need to add a protocol identifier so that QR decoder software knows how to route the extracted data. In this case, the protocol identifier is LPA:, producing:
This string can be passed to any QR code generation software. There are many online services available — here is an example using the Google charts API:
The cht parameter indicates the chart type; the chs parameter is its size. The chl parameter is the data to be encoded. By default this is a UTF-8 string. The API returns the code as a PNG format graphic.
If you use a command line tool like curl, make sure you include the encoded data in single quotes to prevent the shell from attempting to substitute values for what it will otherwise assume to variable names.
Default SM-DP+
You will need to provision the target device with the SM-DP+ address you received earlier. If you are working with an eSIM-compatible Android or iOS device, each OS' Settings app provides a path to enter this information manually — for more information, please see Get Started with Super SIM eSIM Profiles for eUICCs. For an embedded device, however, you will need to consult your LPA provider to learn how to code your application to provision the LPA with the address after retrieving it from your cloud.
3. Install the eSIM profile
Again, this stage will depend on your chosen download method.
Activation Code
Devices that allow the user to input an Activation Code, either by keying in the code manually or by scanning a QR code derived from it, will extract the SM-DP+ address and Matching ID and pass them to the LPA, which will contact the server at that time and retrieve the eSIM profile.
Default SM-DP+
In the case of the Default SM-DP+ method, installation typically takes place when the LPA first starts up and there is no profile in the eUICC: it will contact the provisioned server and pass the host EID. The server will respond with the eSIM profile for installation. If the SM-DP+ server address has just been entered manually — for example, into an Android or iOS device — then the LPA will contact the server at that time.
Take a look at the guide Get Started with Super SIM eSIM Profiles for eUICCs to see how to apply the installation methods to Android and iOS devices.
A Super SIM profile can be downloaded only once to an eSIM. Once it is downloaded, it can be used only with that eSIM. It cannot be downloaded again or used with another eSIM.
Last updated
