Course: Lock SIM to the first device (IMEI) that used it

By using tags, webhooks, and the API you can lock a SIM to the first device it was inserted into

Introduction

Using the tags, webhooks, and the API you can build powerful automization. In this course we will look into how you can easily lock a SIM to the first device that used it.

An IMEI is the id of any mobile device. With Onomondo you can use a feature called IMEI Lock. It means that if a SIM is inserted into another mobile device it will not work. It is a good safeguard to avoid misuse in case a device is stolen.

There can be many ways of building this, so this is just one way of doing it.

The simple idea is that our webhook service will be called when a SIM with this tag comes online, then we set an IMEI lock, and remove the tag.

  1. Create a tag
  2. Create an API key
  3. Create your webhook service
  4. Create a webhook

The code is available on github and can be deployed directly to Heroku.

button

1. Create a tag

First create a tag. In this example we call it "Never Used", but it can be called anything. This tag will be added to all new sims. It is important that it has write access.

After the tag has been created you will see the ID of the tag. This is important for later.

2. Create an API key

Now we need to create an API key. If you already have one you don't need another one. In general it's a good to create multiple ones for each use. It makes it easier to control and revoke access.

To restrict access only give it access to resources tagged with the "Never Used" tag. This makes sure that if someone gets a hold of the key they are not able to affect all of your fleet.

After you create the API key remember to save it. It is never shown again, and is not known by the Onomondo team. Don't worry if you forgot to save it. Simple remove the newly created API key and create another one.

3. Create your webhook service

As mentioned you can implement your webhook service any way you want. The only thing that's important is that it has an HTTPS endpoint that Onomondo can reach it on. Many services like Zapier or IFTTT make you able to not write any code. For this example we'll write some code in Node.js, but you should be able to easily convert it to any other language.

The two calls we need to do is PATCH /sims/$simId and DELETE /sims/$simId/tags/$tagId. The documentation go into more details.

The webhook will be called with this JSON:

{
"type": "network-registration",
"id": "12361237-1233-4123-123d-123a123a123c",
"session_id": "91239123-1236-1239-1233-123d123123",
"time": "2021-11-10T13:17:27.943Z",
"sim_id": "000000005",
"iccid": "89457387300000000019",
"imei": "355123123123123",
"network_type": "4G",
"network": {
"name": "TDC A/S",
"country": "Denmark",
"country_code": "DK",
"mcc": "238",
"mnc": "01"
},
"ipv4": "100.64.123.123",
"sim_label": "my-test-sim"
}

You can find our example code on our github in a repo you can also directly deploy to Heroku. The example code looks similar to this:

const express = require('express')
const axios = require('axios')

const API_KEY = 'YOUR_API_KEY_GOES_HERE'
const TAG_ID = 'YOUR_TAG_ID_GOES_HERE'

const app = express()

axios.defaults.baseURL = 'https://api.onomondo.com'
axios.defaults.headers.common['authorization'] = API_KEY

app.post('/imei_lock', express.json(), async (req, res) => {
const simId = req.body.sim_id
const imei = req.body.imei

console.log(`Received webhook request: ${req.body}`)

// Set the IMEI Lock
await axios.patch(`/sims/${simId}`, { imei_lock:imei })

// Remove the tag from the sim, ensuring that this webhook is not called again
await axios.delete(`/sims/${simId}/tags/${TAG_ID}`)

console.log(`Done setting IMEI lock for ${simId}`)

res.end()
})

app.listen(process.env.PORT || 8145)

4. Create a webhook

Now we set up the webhook. In this example we call it "Automatic IMEI Lock".

You need to give it the URL to your webhook service. If you put your service on Heroku it could https://automatic-imei-lock-service.herokuapp.com. If you don't have your service online just yet, and just want to test webhooks then it can be helpful to use Webhook.site which makes it easy to get set up before implementing anything.

Limit the webhook to the tag we created before. This means that only events from SIMs with this tag will be sent to your webhook service. Otherwise you will receive events from all your SIMs.

The only events we're interested in is the "Network Registration" so just uncheck all the others.

 

 

Run it all

When everything is set up it's time to try it out.

1. Go to the app and give one of your SIMs the tag "Never Used"

2. Insert the SIM into a device (if you have a Getting Started Kit you can use that)

3. Turn it on

4. Your webhook service should now be called, and set the IMEI lock, as well as remove the "Never Used" tag.

If deployed on Heroku then the output will look similar to:

Summary

In this course we looked into how to use the Onomondo API and Webhooks to set up a webhook service that, when called, will set an IMEI lock the first time a SIM is seen.

Even though you may need to do something different this should help you get started on using Webhooks and the API on Onomondo.