Soracom Air for Cellular

Using Tags with a Soracom IoT SIM

Tags provide an easy way to add information to your IoT SIMs to simplify management and identification. You can add tags to describe a device's deployment location, what hardware it uses, the type of function it performs in your application, or which project it belongs to. Afterwards, you can easily search by the tag in order to quickly find your Air device.

Tags can be added to individual Air devices, or they can be added to Groups. Tags between Air devices and Groups are isolated, meaning that an Air device that belongs to a Group does not inherit any tags associated with the Group.

Individual SIM Tags

To add tags to an individual IoT SIM:

  1. Login to the User Console. From the Menu, open the SIM Management screen.

  2. From the list of subscribers, click the for the SIM you want to modify, then click the Details button.

    https://console.soracom.io

    Subscriber details

  3. Click the Tags tab.

    SIM Tags

  4. Click the button to add a new tag. Then enter a name and value for the tag.

IoT SIM Name

The name of an IoT SIM is a tag that can be set through the User Console.

To add or edit the name of an IoT SIM:

  1. Login to the User Console. From the Menu, open the SIM Management screen.

  2. Hover your mouse over the Name column for a particular SIM.

  3. An icon will appear. Click this icon to bring up the option to name or change the name of your SIM.

    Change Name

Group Tags

To add tags to a Group:

  1. Login to the User Console. From the Menu, open the Groups screen.

  2. From the list of groups, click the name of the group you want to configure to open its settings page.

  3. Click the Advanced settings tab.

    https://console.soracom.io

    Group Tags

  4. From the Tags panel, click the button to add a new tag. Then enter a name and value for the tag.

Programmatic Usage

Tags can be managed programmatically using the Soracom API, Soracom CLI, or Metadata Service.

Soracom API

To access the Soracom API, first use the auth API to obtain an API Key and Token. Refer to the API Reference Guide for instructions on how to use the API Key and Token in API requests.

Then, use the putSubscriberTags API to add tags to an IoT SIM:

curl -X PUT \
>  -H 'X-Soracom-API-Key: <MY-API-KEY>' \
>  -H 'X-Soracom-Token: <MY-TOKEN>' \
>  -d '[
>        {
>          "tagName": "my-tag",
>          "tagValue": "my-value"
>        }
>      ]' \
>  https://g.api.soracom.io/v1/subscribers/<IMSI>/tags

Note that the payload is specified as a JSON array of objects, each with a tagName and tagValue attribute. Tags will be updated individually, allowing you to specify which tags you want to add or update without affecting any other tags the IoT SIM may already have.

You can then retrieve tags using the getSubscriber API:

curl -X GET \
>  -H 'X-Soracom-API-Key: <MY-API-KEY>' \
>  -H 'X-Soracom-Token: <MY-TOKEN>' \
>  https://g.api.soracom.io/v1/subscribers/<IMSI>

Or delete a tag using the deleteSubscriberTag API:

curl -X DELETE \
>  -H 'X-Soracom-API-Key: <MY-API-KEY>' \
>  -H 'X-Soracom-Token: <MY-TOKEN>' \
>  https://g.api.soracom.io/v1/subscribers/<IMSI>/tags/<TAG-NAME>

Group Tags are managed similarly with the following APIs:

  • putGroupTags - sets tag(s) for a specified group
  • getGroup - gets all information about a specified group, including its tags
  • deleteGroupTag - deletes a specific tag from a specified group

Soracom CLI

To use the Soracom CLI, you must first configure it to authenticate with your account information, authorization key, or SAM user credentials.

Run the following command to add tags to an IoT SIM:

soracom subscribers put-tags --imsi <IMSI> --body "<TAGS>" --coverage-type g

Here, the JSON array from the API example above should be passed into the --body parameter.

You can then retrieve tags using the this command:

soracom subscribers get --imsi <IMSI> --coverage-type g

Or delete a tag using this command:

soracom subscribers delete-tag --imsi <IMSI> --tag-name "<TAG-NAME>" --coverage-type g

Group Tags are managed similarly using the following commands:

  • soracom groups put-tags - sets tag(s) for a specified group
  • soracom groups get - gets all information about a specified group, including its tags
  • soracom groups delete-tag - deletes a specific tag from a specified group

Metadata Service

The Metadata Service allows an Air SIM device to access and configure its own settings without the need for authentication. For more information, refer to the Metadata Service documentation.

With the Metadata Service option enabled, use the putSubscriberTags API to add tags to the IoT SIM:

curl -X PUT \
>  -d '[
>        {
>          "tagName": "my-tag",
>          "tagValue": "my-value"
>        }
>      ]' \
>  http://metadata.soracom.io/v1/subscriber/tags

You can retrieve tags using the getSubscriber API:

curl http://metadata.soracom.io/v1/subscriber

Or delete a tag using the deleteSubscriberTag API:

curl -X DELETE http://metadata.soracom.io/v1/subscriber/tags/<TAG-NAME>