# Basic Usage Overview of using groups to manage multiple SIMs. Basic Group operations are very simple. Groups are deeply integrated with the Soracom User Console, ensuring that creating a Group and managing its options is easy to access. While Groups can be accessed from several parts of the User Console, the following examples show basic usage from the Soracom Air for Cellular screens. ## Managing Groups ### Creating a Group 1. Sign in to the **[User Console](https://console.soracom.io/?coverage_type=g)**. From the **☰ Menu**, open the **Groups** screen. 2. Click the **+ Add Group** button. ![Add Group](https://docs.soracom.io/_astro/add-group.B-K8CRd-_HBrm0.webp) 3. Enter a name for your group, then click **Create**. ![Create Group](https://docs.soracom.io/_astro/create-group.C7qysf9T_ZfzWKq.webp) When you create a new group, it will automatically be assigned an **ID**. This ID is required when performing actions to the group using the Soracom API or Soracom CLI. > [!WARNING] > > You can also create a group when [registering a new IoT SIM](https://docs.soracom.io/en/services/air/registration), or when [adding a device to a group](https://docs.soracom.io/en/services/groups/usage/#adding-a-device-to-a-group). ### Copying a Group You can copy an existing group to quickly create a new group with the same configuration. [Watch Options](https://docs.soracom.io/en/services/groups/settings#watch-options) are not carried over to the copied 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 copy to open its settings page. 3. Click the **Copy this group** button. The copied group will be created with the same configuration as the original group. The new group's name will be the original group name with `copy` appended to it. > [!WARNING] > > The Soracom API and Soracom CLI do not provide a direct method to copy a group. To copy a group, retrieve the configuration of an existing group and create a new group with that configuration. > > - When using the Soracom API, use the [getGroup](https://docs.soracom.io/en/api#!/Group/getGroup) or [listGroups](https://docs.soracom.io/en/api#!/Group/listGroups) API to retrieve the configuration of an existing group, then use the [createGroup](https://docs.soracom.io/en/api#!/Group/createGroup) API to create a new group. > - When using the Soracom CLI, use `soracom groups get` or `soracom groups list` to retrieve the configuration of an existing group, then use `soracom groups create` to create a new group. ### Renaming 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 rename to open its settings page. ![Group Details](https://docs.soracom.io/_astro/group-details.BA5x2CfU_Z1n0X1g.webp) 3. From the group settings page, click the **✏** icon next to the current group name. 4. Enter the new name for your group, then click the **☑** to save. ### Deleting a Group A group can only be deleted if there are no devices attached to the group. If your group contains any devices, remove them from the group first. 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 delete to open its settings page, then click the **Delete this group** button. ![Group Details](https://docs.soracom.io/_astro/group-details-delete.D08CKg5B_Z2dLzxa.webp) 3. A warning will appear asking you to confirm deletion. Click **Delete** to delete the group. ## Managing Devices The following instructions are for Air for Cellular devices, but also apply to Air for Sigfox, Air for LoRaWAN, and Soracom Inventory devices. Simply open the **Sigfox Devices**, **LoRa Devices**, or **Device Management** screens respectively. ### Adding a Device to a Group 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. 3. Click the **Actions ▾** menu, then select **Change group**. ![Change Group](https://docs.soracom.io/_astro/change-group.C0QarGMW_1ObdPM.webp) 4. From the Update selected subscribers group dialog, select the group you want to set for the IoT SIM device, then click **Change Group**. ![Select Group](https://docs.soracom.io/_astro/set-group.00qNI-6k_Z282uG4.webp) > [!WARNING] > > You can also create a new group by selecting the **Create group...** option. ### Removing a Device from a Group 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. 3. Click the **Actions ▾** menu, then select **Change group**. ![Change Group](https://docs.soracom.io/_astro/change-group.C0QarGMW_1ObdPM.webp) 4. From the Update selected subscribers group dialog, select **Unset group**, then click **Change Group**. ![Unset Group](https://docs.soracom.io/_astro/unset-group.BjdCmeFN_U8utv.webp) ## Programmatic Usage You can manage Groups programmatically using the Soracom API or Soracom CLI. In addition to create, rename, delete, add, and remove actions, the API and CLI provides the ability to list subscribers in each group, as well as configure various group parameters. Refer to the API reference or CLI documentation for further information. ### 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 [createGroup](https://docs.soracom.io/en/api#!/Group/createGroup) API to create a group: **Global** ```bash curl -X POST \ -H 'X-Soracom-API-Key: ' \ -H 'X-Soracom-Token: ' \ -H 'Content-Type: application/json' \ -d '{ "tags": { "name": "my-group" } }' \ https://g.api.soracom.io/v1/groups ``` **Japan** ```bash curl -X POST \ -H 'X-Soracom-API-Key: ' \ -H 'X-Soracom-Token: ' \ -H 'Content-Type: application/json' \ -d '{ "tags": { "name": "my-group" } }' \ https://jp.api.soracom.io/v1/groups ``` Once the group is created, the API will return a response which includes the group ID. You can then use this ID for additional group-related APIs. A group's name is stored in the **name** attribute of its **tags**. To rename a group, simply update its tags using the [putGroupTags](https://docs.soracom.io/en/api#!/Group/putGroupTags) API: **Global** ```bash curl -X PUT \ -H 'X-Soracom-API-Key: ' \ -H 'X-Soracom-Token: ' \ -H 'Content-Type: application/json' \ -d '[ { "tagName": "name", "tagValue": "my-new-group" } ]' \ https://g.api.soracom.io/v1/groups//tags ``` **Japan** ```bash curl -X PUT \ -H 'X-Soracom-API-Key: ' \ -H 'X-Soracom-Token: ' \ -H 'Content-Type: application/json' \ -d '[ { "tagName": "name", "tagValue": "my-new-group" } ]' \ https://jp.api.soracom.io/v1/groups//tags ``` To delete the group, use the [deleteGroup](https://docs.soracom.io/en/api#!/Group/deleteGroup) API: **Global** ```bash curl -X DELETE \ -H 'X-Soracom-API-Key: ' \ -H 'X-Soracom-Token: ' \ https://g.api.soracom.io/v1/groups/ ``` **Japan** ```bash curl -X DELETE \ -H 'X-Soracom-API-Key: ' \ -H 'X-Soracom-Token: ' \ https://jp.api.soracom.io/v1/groups/ ``` To add an IoT SIM to a group, use the [setSimGroup](https://docs.soracom.io/en/api#!/Sim/setSimGroup) API: **Global** ```bash curl -X POST \ -H 'X-Soracom-API-Key: ' \ -H 'X-Soracom-Token: ' \ -H 'Content-Type: application/json' \ -d '{ "groupId": "" }' \ https://g.api.soracom.io/v1/sims//set_group ``` **Japan** ```bash curl -X POST \ -H 'X-Soracom-API-Key: ' \ -H 'X-Soracom-Token: ' \ -H 'Content-Type: application/json' \ -d '{ "groupId": "" }' \ https://jp.api.soracom.io/v1/sims//set_group ``` And to remove it from a group, use the [unsetSimGroup](https://docs.soracom.io/en/api#!/Sim/unsetSimGroup) API: **Global** ```bash curl -X POST \ -H 'X-Soracom-API-Key: ' \ -H 'X-Soracom-Token: ' \ https://g.api.soracom.io/v1/sims//unset_group ``` **Japan** ```bash curl -X POST \ -H 'X-Soracom-API-Key: ' \ -H 'X-Soracom-Token: ' \ https://jp.api.soracom.io/v1/sims//unset_group ``` Groups for Sigfox, LoRaWAN, and Soracom Inventory devices are managed similarly using the following API methods: - [setSigfoxDeviceGroup](https://docs.soracom.io/en/api#!/SigfoxDevice/setSigfoxDeviceGroup) and [unsetSigfoxDeviceGroup](https://docs.soracom.io/en/api#!/SigfoxDevice/unsetSigfoxDeviceGroup) - [setLoraDeviceGroup](https://docs.soracom.io/en/api#!/LoraDevice/setLoraDeviceGroup) and [unsetLoraDeviceGroup](https://docs.soracom.io/en/api#!/LoraDevice/unsetLoraDeviceGroup) - [setDeviceGroup](https://docs.soracom.io/en/api#!/Device/setDeviceGroup) and [unsetDeviceGroup](https://docs.soracom.io/en/api#!/Device/unsetDeviceGroup) ### 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, use the `groups create` command to create a group: **Global** ```bash soracom groups create --body '{ "tags": { "name": "my-group" } }' --coverage-type g ``` **Japan** ```bash soracom groups create --body '{ "tags": { "name": "my-group" } }' --coverage-type jp ``` Once the group is created, the CLI will return a response which includes the group ID. You can then use this ID for additional group-related commands. Similar to the API example above, we can update a group's tags with the `groups put-tags` command in order to rename it: **Global** ```bash soracom groups put-tags --group-id '' --body '[ { "tagName": "name", "tagValue": "my-new-group" } ]' --coverage-type g ``` **Japan** ```bash soracom groups put-tags --group-id '' --body '[ { "tagName": "name", "tagValue": "my-new-group" } ]' --coverage-type jp ``` To delete the group, use the `groups delete` command: **Global** ```bash soracom groups delete --group-id '' --coverage-type g ``` **Japan** ```bash soracom groups delete --group-id '' --coverage-type jp ``` To add an IoT SIM to a group, use the `sims set-group` command: **Global** ```bash soracom sims set-group --sim-id --group-id '' --coverage-type g ``` **Japan** ```bash soracom sims set-group --sim-id --group-id '' --coverage-type jp ``` And to remove it from a group, use the `sims unset-group` command: **Global** ```bash soracom sims unset-group --sim-id --coverage-type g ``` **Japan** ```bash soracom sims unset-group --sim-id --coverage-type jp ``` Groups for Sigfox, LoRaWAN, and Soracom Inventory devices are managed similarly using the following commands: - `soracom sigfox-devices set-group` and `soracom sigfox-devices unset-group` - `soracom lora-devices set-group` and `soracom lora-devices unset-group` - `soracom devices set-group` and `soracom devices unset-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. When the Metadata Service is enabled, an Air for Cellular device can set or unset its own group configuration. Use the Subscriber [setGroup](https://docs.soracom.io/en/api#!/Subscriber/setGroup) API to assign the IoT SIM to a group: ```bash curl -X POST \ -H 'Content-Type: application/json' \ -d '{ "groupId": "" }' \ http://metadata.soracom.io/v1/subscriber/set_group ``` And to remove it from a group, use the Subscriber [unsetGroup](https://docs.soracom.io/en/api#!/Subscriber/unsetGroup) API: ```bash curl -X POST \ http://metadata.soracom.io/v1/subscriber/unset_group ``` When changing an IoT SIM's group assignment, not all options will take effect immediately. Your device may need to disconnect from the network and reconnect in order to load settings from a new group assignment.