# Tags

Organize SIMs with tags for searching, grouping, and automation.

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. Sign in to the **[User Console](https://console.soracom.io/?coverage_type=g)**. 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.

   ![Subscriber details](https://docs.soracom.io/_astro/tags-subscriber-details.DNjSsLAY_Z2LdYH.webp)

3. Click the **Tags** tab.

   ![SIM Tags](https://docs.soracom.io/_astro/sim-tags.CMwp1UbX_6UuN9.webp)

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. Sign in to the **[User Console](https://console.soracom.io/?coverage_type=g)**. 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](https://docs.soracom.io/_astro/change-name.DqZOdk9f_2PrXR.webp)

## Group Tags

To add tags to a Group:

1. Sign in to the **[User Console](https://console.soracom.io/?coverage_type=g)**. 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.

   ![Group Tags](https://docs.soracom.io/_astro/group-tags.De76xGyx_1nHVKf.webp)

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**](https://docs.soracom.io/en/api#!/Auth/auth) API to obtain an API Key and Token. Refer to the [**API Usage Guide**](https://docs.soracom.io/en/developers/soracom-api) for instructions on how to use the API Key and Token in API requests.

Then, use the [putSimTags](https://docs.soracom.io/en/api#!/Sim/putSimTags) API to add tags to an IoT SIM:

**Global**

```bash
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/sims/<SIM-ID>/tags
```

**Japan**

```bash
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://jp.api.soracom.io/v1/sims/<SIM-ID>/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 [getSim](https://docs.soracom.io/en/api#!/Sim/getSim) API:

**Global**

```bash
curl -X GET \
  -H 'X-Soracom-API-Key: <MY-API-KEY>' \
  -H 'X-Soracom-Token: <MY-TOKEN>' \
  https://g.api.soracom.io/v1/sims/<SIM-ID>
```

**Japan**

```bash
curl -X GET \
  -H 'X-Soracom-API-Key: <MY-API-KEY>' \
  -H 'X-Soracom-Token: <MY-TOKEN>' \
  https://jp.api.soracom.io/v1/sims/<SIM-ID>
```

Or delete a tag using the [deleteSimTag](https://docs.soracom.io/en/api#!/Sim/deleteSimTag) API:

**Global**

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

**Japan**

```bash
curl -X DELETE \
  -H 'X-Soracom-API-Key: <MY-API-KEY>' \
  -H 'X-Soracom-Token: <MY-TOKEN>' \
  https://jp.api.soracom.io/v1/sims/<SIM-ID>/tags/<TAG-NAME>
```

Group Tags are managed similarly with the following APIs:

- [putGroupTags](https://docs.soracom.io/en/api#!/Group/putGroupTags) - sets tag(s) for a specified group
- [getGroup](https://docs.soracom.io/en/api#!/Group/getGroup) - gets all information about a specified group, including its tags
- [deleteGroupTag](https://docs.soracom.io/en/api#!/Group/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:

**Global**

```bash
soracom sims put-tags --sim-id <SIM-ID> --body "<TAGS>" --coverage-type g
```

**Japan**

```bash
soracom sims put-tags --sim-id <SIM-ID> --body "<TAGS>" --coverage-type jp
```

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:

**Global**

```bash
soracom sims get --sim-id <SIM-ID> --coverage-type g
```

**Japan**

```bash
soracom sims get --sim-id <SIM-ID> --coverage-type jp
```

Or delete a tag using this command:

**Global**

```bash
soracom sims delete-tag --sim-id <SIM-ID> --tag-name "<TAG-NAME>" --coverage-type g
```

**Japan**

```bash
soracom sims delete-tag --sim-id <SIM-ID> --tag-name "<TAG-NAME>" --coverage-type jp
```

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**](https://docs.soracom.io/en/services/air/metadata-service) documentation.

With the Metadata Service option enabled, use the [putSubscriberTags](https://docs.soracom.io/en/api#!/Subscriber/putSubscriberTags) API to add tags to the IoT SIM:

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

You can retrieve tags using the [getSubscriber](https://docs.soracom.io/en/api#!/Subscriber/getSubscriber) API:

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

Or delete a tag using the [deleteSubscriberTag](https://docs.soracom.io/en/api#!/Subscriber/deleteSubscriberTag) API:

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