Twilio’s Super SIM API allows Internet of Things manufacturers who have chosen to incorporate eSIMs into their products to take full advantage of Super SIM’s global connectivity via multiple tier-1 networks, all selected and managed through a single API.
To access Super SIM connectivity, each of your eSIMs will need to be loaded with a Super SIM profile reserved for that particular eSIM. The API provides tools for you to create such profiles. Once that’s done, you manage the eSIM using a Sim resource, just as you would with any other Super SIM. You assign it to a Fleet and activate it when required.
Additionally, you will need to code your device firmware to communicate with the Twilio profile server, request the profile reserved for the device’s eSIM, and then install the downloaded profile into the device’s eUICC — the physical embodiment of the eSIM. Some of this functionality may be provided by your eUICC, or you may need to develop and install additional code. Either way, your eUICC supplier can assist you with these tasks.
A typical call flow for downloading Super SIM profiles
This short tutorial will introduce you to the API part of the process. It uses a commonly available eSIM-compatible device, the Apple iPad, as a stand-in for your IoT device because it too makes use of consumer eSIM profiles and so will give you a clear picture of the device side of the process. However, all the API calls used in the walkthrough and the sequence of steps is the same whatever device you are building.
First, though, here’s a brief recap of how eSIMs differ from traditional SIMs, how they work, and how they are configured for connectivity remotely. If you’re already familiar with this, that’s fine — just jump straight to the Try it Out section.
Traditional SIMs, whether they are cards or embedded chips, contain connectivity settings, called a ‘profile’, for a single connectivity provider. This provider may be a mobile network operator or a company like Twilio that leverages networks from all over the world. The SIM’s profile is baked in at manufacture and can’t be changed.
eSIMs, on the other hand, are devices that can download profiles over the air. Unlike a traditional SIM they can even host multiple profiles and allow the host device’s manufacturer or end-user to switch between them at will. Think of each profile on an eSIM as a digital SIM. Switching from one profile to another is the digital equivalent of swapping SIM cards.
An eSIM is embodied in a device called an Embedded Universal Integrated Circuit Card (eUICC). For this reason, the term ‘eUICC’ is often used interchangeably with ‘eSIM’.
One more thing. There are two different types of eSIM profile, consumer and M2M, and they are not interchangeable. Twilio currently supports consumer profiles only. If you’d like to learn more about the differences and why Twilio believes in consumer profiles for IoT, have a look at out blog post The Benefits of Consumer Profile eSIMs for IoT Devices.
First, your device needs a Local Profile Assistant (LPA). This is the code which downloads, installs and manages profiles on the device’s eUICC. It also provides an interface through which users swap the current profile for another to switch between cellular connectivity providers.
The LPA may be part of a device’s application or operating system, or it may be built into the eUICC. For example, newer Android and iOS devices that are eSIM compatible already have this on board. For IoT devices, you will need to discuss with your modem supplier how to develop and install a suitable LPA for your choice of hardware and operating system. If your choice of eUICC contains an LPA, you will still need to code your application to communicate with it.
The IoT device, a hire bike, requests and downloads a Super SIM profile to its eSIM in order to get connected to its manufacturer
To install an eSIM profile, you give the LPA the address of an SM-DP+ (Subscription Manager Data Preparation) server. This online resource stores eSIM profiles waiting to be downloaded. Think of it as a virtual warehouse full of digital SIMs.
The SM-DP+ can also hold profile activation and confirmation codes. If you’ve ever installed an eSIM profile using a QR code, for example, the SM-DP+ address and these values are embedded in that code.
However the LPA gets the address of an SM-DP+ server, it will contact that server to download and install a profile in the eUICC. If you entered the SM-DP+ manually, or it has been pre-programmed into the LPA by your application, the LPA sends the host’s eUICC’s ID (EID) and receives the profile that has been reserved exclusively for that EID. Once the eSIM profile has been installed and activated, the host device is able to connect to the Internet.
The Super SIM eSIM Profiles API provides the tools for you to generate eSIM profiles that are support Super SIM connectivity — the digital equivalent of a regular Super SIM. Let’s see how that’s done — and how you get a device to download and use a Super SIM profile you have created.
You can get a clear picture of how the Super SIM API’s eSIM Profiles functionality works by trying it out for yourself. iPad Pros released since 2018, and iPads, iPad Airs and iPad Minis released since 2019, all include an eSIM. This makes the Apple tablet a great way to evaluate Super SIM eSIM Profiles before implementing them in your own IoT product.
iOS does not always play nicely with Super SIM. Every Super SIM will switch between multiple IMSIs depending on the country in which the device is being used. For some IMSIs, iOS, particularly on iPhones, may prevent you from changing from the APN. If you can’t change the APN to
super, you will not be able to use data. Tools like Apple Configurator can help you get around this limitation if iOS is preventing you from setting the APN.
In addition to a recent iPad, you’ll also need a computer which you’ll use to interact with the Super SIM API through a terminal app. The commands are shown from the perspective of a Unix machine like a Mac or a Linux box, but they can also be run under Windows 10 PowerShell or Windows Terminal — you’ll just see a slightly different prompt.
The crucial point is that, from an API perspective, the actions you’ll perform in the steps below will be exactly the same as those you’ll implement to provision the off-the-shelf eUICCs in your IoT devices.
Let’s get started.
- At the home screen, tap on Settings.
- Go to General > About and scroll down to EID:
- Write down your iPad’s EID — you’ll need it in the next step — or keep the iPad turned on beside you.
- On your computer, enter the following command in a terminal, making sure you replace
<YOUR_IPAD_EID>with the value you noted down in Step 1. Enter it carefully — it’s a 32-digit number, so it’s easy to mis-key. You’ll also need your usual Twilio access credentials: add them in place of the
<YOUR_AUTH_TOKEN>, respectively. If you need to remind yourself of these values, you can get them from the Console.
curl -X POST https://supersim.twilio.com/v1/ESimProfiles \ -d "Eid=<YOUR_IPAD_EID>" \ -u "<YOUR_ACCOUNT_SID>:<YOUR_AUTH_TOKEN>"
- The command above will return a JSON object, which curl will print in the terminal. Look through it for the
urlkey and copy its value, which will look something like this:We’ll use this URL in the next step.
- Run the following command:
curl -X GET <YOUR_ESIM_PROFILE_URL> \ -u "<YOUR_ACCOUNT_SID>:<YOUR_AUTH_TOKEN>"
- In the JSON displayed by curl, check the value of the
statuskey. When it is
available, you’re ready for the next step, but you may see
reservinginstead. This means Twilio is still in the process of setting up the new SIM Profile for the specified EID. Please wait a couple of minutes and try again. In a real-world application, you’d add a callback URL to the API call. Twilio will post notifications to this URL whenever the eSIM Profile’s status changes and when it is eventually downloaded to its target eSIM.
- When the eSIM Profile has been reserved and set to the available state, Twilio creates a Sim resource to represent the eSIM in your device. From this point, you’ll use this Sim resource just like any other Super SIM. The new Sim’s SID is the value of the
sim_sidkey in the output from Step 3. Make a note of it; you’ll use it in a moment to activate it and add it to a Fleet.
If you already have a Fleet resource, you can go straight to Step 5. If not, you’ll need to create a Fleet now and set up its Network Access Profile — the list of global cellular networks its member SIMs are able to connect to. If you need a hand, jump to our Network Access Profiles guide and we’ll show you how to do this.
- In addition to the
sim_sidkey, grab the value of the
smdp_plus_addresskey. This is the address of the SM-DP+ server your iPad will contact to download its new eSIM Profile. You’ll enter it into your iPad settings in Step 6.
- These two operations are carried out with a single command. Just replace
<YOUR_SIM_SID>with the Sim SID you retrieved in the previous step, and
<YOUR_FLEET_SID>with the target Fleet’s SID:
curl -X POST https://supersim.twilio.com/v1/Sims/<YOUR_SIM_SID> \ -d "Status=active" \ -d "Fleet=<YOUR_FLEET_SID>" \ -u "<YOUR_ACCOUNT_SID>:<YOUR_AUTH_TOKEN>"
- It’s back to the iPad now. Go to Settings > Mobile Data or Settings > Cellular Data. Which of these you’ll see will depend on your region.
- Scroll down and tap Add Data Plan or Add Cellular Plan. If you’re working with a new iPad, you’ll see a list of network providers, but just tap Other...:
- The iPad UI is designed to scan a QR code from an operator, but you should instead tap on Enter Details Manually at the bottom of the screen:
- Enter the value of the
smdp_plus_addresskey you got in Step 5 into the SM-DP+ Address field. Leave the other two fields blank:
- Tap Next. Behind the scenes, iOS’ LPA contacts the SM-DP+ server, supplies the iPad’s EID, and is informed that there is a reserved eSIM profile available for the device. A prompt will appear to tell you that you have a plan ready to be added and asking you if you wish to proceed.
- Tap the Add Data Plan or Add Cellular Plan button:
- There’ll be a short period while the LPA downloads the plan — the eSIM profile, in other words — and activates it. The main Mobile Data settings will be disabled while activation is taking place.
The plan will come from Twilio, but you may see the name of a Twilio partner network instead. If this happens, don’t worry — you’ll still be applying a Twilio plan, and you will use the Twilio APN in the next step.
- You’re almost done. Tap on Mobile Data Options or Cellular Data Options. Again, which of these you see will depend on your region.
- Enable roaming by turning on the Data Roaming switch.
- Go back to the previous screen and tap on APN Settings.
superin the first APN field. Don’t enter a username or password:
And you’re done. Your iPad’s eSIM will now connect to the Internet via the Twilio Distributed IoT Mobile Core and any of the cellular networks across the globe that you have assigned to the Network Access Profile associated with your eSIM’s Fleet. Make sure the iPad’s WiFi connectivity is turned off and try visiting some websites.
Open the Safari browser and enter https://www.twilio.com/docs/iot/supersim/api to find out more about the functionality offered by the Super SIM API.
You’ve learned how eSIMs work and how they are configured with eSIM profiles. You’ve seen how the Twilio Super SIM API makes it easy to set up new eSIM profiles and use each one’s associated Sim resource to bring connectivity to a device.
In the tutorial, that device was an iPad, but it could just as easily have been any IoT device that you, or your end-users, will deploy. It works just the same way. You can take any off-the-shelf eUICC hardware compatible with the consumer eSIM profile specification and which is running an LPA, create and install a Super SIM eSIM profile onto it, and by doing so allow it to connect through mobile networks across the globe.