Using Tags with Soracom Air

Tags provide an easy way to add information to your Air SIMs to simplify management and searching. 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. Then 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 Air SIM Tags

To add tags to an individual Air SIM device:

  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.

Group Tags

To add tags to an Air SIM 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 Air 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 Air 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:

Soracom CLI

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

Then, run the following command to add tags to an Air SIM:

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

Here, the JSON array from the API example above should be passed in to 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