# Tagging your AWS IoT resources
To help you manage and organize your thing groups, thing types, topic rules, jobs, scheduled audits and security profiles you can optionally assign your own metadata to each of these resources in the form of tags. This section describes tags and shows you how to create them.
To help you manage your costs related to things, you can create [billing groups](tagging-iot-billing-groups.md) that contain things. You can then assign tags that contain your metadata to each of these billing groups. This section also discusses billing groups and the commands available to create and manage them.
## Tag basics
You can use tags to categorize your AWS IoT resources in different ways (for example, by purpose, owner, or environment). This is useful when you have many resources of the same type — you can quickly identify a resource based on the tags you've assigned to it. Each tag consists of a key and optional value, both of which you define. For example, you can define a set of tags for your thing types that helps you track devices by type. We recommend that you create a set of tag keys that meets your needs for each kind of resource. Using a consistent set of tag keys makes it easier for you to manage your resources.
You can search for and filter resources based on the tags you add or apply. You can also use billing group tags to categorize and track your costs. You can also use tags to control access to your resources as described in [Using tags with IAM policies](tagging-iot-iam.md).
For ease of use, the Tag Editor in the AWS Management Console provides a central, unified way to create and manage your tags. For more information, see [Working with Tag Editor](https://docs.aws.amazon.com/awsconsolehelpdocs/latest/gsg/tag-editor.html) in [ Working with the AWS Management Console](https://docs.aws.amazon.com/awsconsolehelpdocs/latest/gsg/getting-started.html).
You can also work with tags using the AWS CLI and the AWS IoT API. You can associate tags with thing groups, thing types, topic rules, jobs, security profiles, policies, billing groups, and the packages and versions associated with things when you create them by using the `Tags` field in the following commands:
+ [CreateBillingGroup](https://docs.aws.amazon.com//iot/latest/apireference/API_CreateBillingGroup)
+ [CreateDestination](https://docs.aws.amazon.com//iot-wireless/latest/apireference/API_CreateDestination.html)
+ [CreateDeviceProfile](https://docs.aws.amazon.com//iot-wireless/latest/apireference/API_CreateDeviceProfile.html)
+ [CreateDynamicThingGroup](https://docs.aws.amazon.com//iot/latest/apireference/API_CreateDynamicThingGroup)
+ [CreateJob](https://docs.aws.amazon.com//iot/latest/apireference/API_CreateJob)
+ [CreateOTAUpdate](https://docs.aws.amazon.com//iot/latest/apireference/API_CreateOTAUpdate)
+ [CreatePolicy](https://docs.aws.amazon.com//iot/latest/apireference/API_CreatePolicy.html)
+ [CreateScheduledAudit](https://docs.aws.amazon.com//iot/latest/apireference/API_CreateScheduledAudit)
+ [CreateSecurityProfile](https://docs.aws.amazon.com//iot/latest/apireference/API_CreateSecurityProfile)
+ [CreateServiceProfile](https://docs.aws.amazon.com//iot-wireless/latest/apireference/API_CreateServiceProfile.html)
+ [CreateStream](https://docs.aws.amazon.com//iot/latest/apireference/API_CreateStream)
+ [CreateThingGroup](https://docs.aws.amazon.com//iot/latest/apireference/API_CreateThingGroup)
+ [CreateThingType](https://docs.aws.amazon.com//iot/latest/apireference/API_CreateThingType)
+ [CreateTopicRule](https://docs.aws.amazon.com//iot/latest/apireference/API_CreateTopicRule)
+ [CreateWirelessGateway](https://docs.aws.amazon.com//iot-wireless/latest/apireference/API_CreateWirelessGateway.html)
+ [CreateWirelessDevice](https://docs.aws.amazon.com//iot-wireless/latest/apireference/API_CreateWirelessDevice.html)
You can add, modify, or delete tags for existing resources that support tagging by using the following commands:
+ [TagResource](https://docs.aws.amazon.com//iot/latest/apireference/API_TagResource)
+ [ListTagsForResource](https://docs.aws.amazon.com//iot/latest/apireference/API_ListTagsForResource)
+ [UntagResource](https://docs.aws.amazon.com//iot/latest/apireference/API_UntagResource)
You can edit tag keys and values, and you can remove tags from a resource at any time. You can set the value of a tag to an empty string, but you can't set the value of a tag to null. If you add a tag that has the same key as an existing tag on that resource, the new value overwrites the old value. If you delete a resource, any tags associated with the resource are also deleted.
### Tag restrictions and limitations
The following basic restrictions apply to tags:
+ Maximum number of tags per resource — 50
+ Maximum key length — 127 Unicode characters in UTF-8
+ Maximum value length — 255 Unicode characters in UTF-8
+ Tag keys and values are case sensitive.
+ Do not use the `aws:` prefix in your tag names or values. It's reserved for AWS use. You can't edit or delete tag names or values with this prefix. Tags with this prefix don't count against your tags per resource limit.
+ If your tagging schema is used across multiple services and resources, remember that other services might have restrictions on allowed characters. Allowed characters include letters, spaces, and numbers representable in UTF-8, and the following special characters: \$1 - = . \$1 : / @.
# Using tags with IAM policies
You can apply tag-based resource-level permissions in the IAM policies you use for AWS IoT API actions. This gives you better control over what resources a user can create, modify, or use. You use the `Condition` element (also called the `Condition` block) with the following condition context keys and values in an IAM policy to control user access (permissions) based on a resource's tags:
+ Use `aws:ResourceTag/tag-key: tag-value` to allow or deny user actions on resources with specific tags.
+ Use `aws:RequestTag/tag-key: tag-value` to require that a specific tag be used (or not used) when making an API request to create or modify a resource that allows tags.
+ Use `aws:TagKeys: [tag-key, ...]` to require that a specific set of tag keys be used (or not used) when making an API request to create or modify a resource that allows tags.
**Note**
The condition context keys and values in an IAM policy apply only to those AWS IoT actions where an identifier for a resource capable of being tagged is a required parameter. For example, the use of [DescribeEndpoint](https://docs.aws.amazon.com//iot/latest/apireference/API_DescribeEndpoint) is not allowed or denied on the basis of condition context keys and values because no taggable resource (thing groups, thing types, topic rules, jobs, or security profile) is referenced in this request. For more information about AWS IoT resources that are taggable and condition keys they support, read [Actions, resources, and condition keys for AWS IoT](https://docs.aws.amazon.com/service-authorization/latest/reference/list_awsiot.html).
For more information about using tags, see [Controlling Access Using Tags](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_tags.html) in the *AWS Identity and Access Management User Guide*. The [IAM JSON Policy Reference](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies.html) section of that guide has detailed syntax, descriptions, and examples of the elements, variables, and evaluation logic of JSON policies in IAM.
The following example policy applies two tag-based restrictions for the `ThingGroup` actions. An IAM user restricted by this policy:
+ Can't create a thing group the tag "env=prod" (in the example, see the line `"aws:RequestTag/env" : "prod"`).
+ Can't modify or access a thing group that has an existing tag "env=prod" (in the example, see the line `"aws:ResourceTag/env" : "prod"`).
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Deny",
"Action": "iot:CreateThingGroup",
"Resource": "*",
"Condition": {
"StringEquals": {
"aws:RequestTag/env": "prod"
}
}
},
{
"Effect": "Deny",
"Action": [
"iot:CreateThingGroup",
"iot:DeleteThingGroup",
"iot:DescribeThingGroup",
"iot:UpdateThingGroup"
],
"Resource": "*",
"Condition": {
"StringEquals": {
"aws:ResourceTag/env": "prod"
}
}
},
{
"Effect": "Allow",
"Action": [
"iot:CreateThingGroup",
"iot:DeleteThingGroup",
"iot:DescribeThingGroup",
"iot:UpdateThingGroup"
],
"Resource": "*"
}
]
}
```
You can also specify multiple tag values for a given tag key by enclosing them in a list, like this:
```
"StringEquals" : {
"aws:ResourceTag/env" : ["dev", "test"]
}
```
**Note**
If you allow or deny users access to resources based on tags, you must consider explicitly denying users the ability to add those tags to or remove them from the same resources. Otherwise, it's possible for a user to circumvent your restrictions and gain access to a resource by modifying its tags.
# Billing groups
AWS IoT doesn't allow you to directly apply tags to individual things, but it does allow you to place things in billing groups and to apply tags to these. For AWS IoT, allocation of cost and usage data based on tags is limited to billing groups.
AWS IoT Core for LoRaWAN resources, such as wireless devices and gateways, can't be added to billing groups. However, they can be associated with AWS IoT things, which can be added to billing groups.
The following commands are available:
+ [AddThingToBillingGroup](https://docs.aws.amazon.com//iot/latest/apireference/API_AddThingToBillingGroup) adds a thing to a billing group.
+ [CreateBillingGroup](https://docs.aws.amazon.com//iot/latest/apireference/API_CreateBillingGroup) creates a billing group.
+ [DeleteBillingGroup](https://docs.aws.amazon.com//iot/latest/apireference/API_DeleteBillingGroup) deletes the billing group.
+ [DescribeBillingGroup](https://docs.aws.amazon.com//iot/latest/apireference/API_DescribeBillingGroup) returns information about a billing group.
+ [ListBillingGroups](https://docs.aws.amazon.com//iot/latest/apireference/API_ListBillingGroups) lists the billing groups you have created.
+ [ListThingsInBillingGroup](https://docs.aws.amazon.com//iot/latest/apireference/API_ListThingsInBillingGroup) lists the things you have added to the given billing group.
+ [RemoveThingFromBillingGroup](https://docs.aws.amazon.com//iot/latest/apireference/API_RemoveThingFromBillingGroup) removes the given thing from the billing group.
+ [UpdateBillingGroup](https://docs.aws.amazon.com//iot/latest/apireference/API_UpdateBillingGroup) updates information about the billing group.
+ [CreateThing](https://docs.aws.amazon.com//iot/latest/apireference/API_CreateThing) allows you to specify a billing group for the thing when you create it.
+ [DescribeThing](https://docs.aws.amazon.com//iot/latest/apireference/API_DescribeThing) returns the description of a thing including the billing group the thing belongs to, if any.
The AWS IoT Wireless API provides these actions to associate wireless devices and gateways with AWS IoT things.
+ [AssociateWirelessDeviceWithThing](https://docs.aws.amazon.com//iot-wireless/latest/apireference/API_AssociateWirelessDeviceWithThing.html)
+ [AssociateWirelessGatewayWithThing](https://docs.aws.amazon.com//iot-wireless/latest/apireference/API_AssociateWirelessGatewayWithThing.html)
## Viewing cost allocation and usage data
You can use billing group tags to categorize and track your costs. When you apply tags to billing groups (and so to the things they include), AWS generates a cost allocation report as a comma-separated value (CSV) file with your usage and costs aggregated by your tags. You can apply tags that represent business categories (such as cost centers, application names, or owners) to organize your costs across multiple services. For more information about using tags for cost allocation, see [ Use Cost Allocation Tags](https://docs.aws.amazon.com/awsaccountbilling/latest/aboutv2/cost-alloc-tags.html) in the [AWS Billing and Cost Management User Guide](https://docs.aws.amazon.com/awsaccountbilling/latest/aboutv2/).
**Note**
To accurately associate usage and cost data with those things you have placed in billing groups, each device or application must:
Be registered as a thing in AWS IoT. For more information, see [Managing devices with AWS IoT](iot-thing-management.md).
Connect to the AWS IoT message broker through MQTT using only the thing's name as the client ID. For more information, see [Device communication protocols](protocols.md). If you client ID doesn't match the thing name, you can enable the exclusive thing attachment to establish the association. For more information, see [Associating an AWS IoT thing to an MQTT client connection](exclusive-thing.md).
Authenticate using a client certificate associated with the thing.
The following pricing dimensions are available for billing groups (based on the activity of things associated with the billing group):
+ Connectivity (based on the thing name used as the client ID to connect).
+ Messaging (based on messages inbound from, and outbound to, a thing; MQTT only).
+ Shadow operations (based on the thing whose message triggered a shadow update).
+ Rules triggered (based on the thing whose inbound message triggered the rule; does not apply to those rules triggered by MQTT lifecycle events).
+ Thing index updates (based on the thing that was added to the index).
+ Remote actions (based on the thing updated).
+ [AWS IoT Device Defender detect](https://docs.aws.amazon.com/iot-device-defender/latest/devguide/device-defender-detect.html) reports (based on the thing whose activity is reported).
Cost and usage data based on tags (and reported for a billing group) doesn't reflect the following activities:
+ Device registry operations (including updates to things, thing groups, and thing types). For more information, see [Managing devices with AWS IoT](iot-thing-management.md)).
+ Thing group index updates (when adding a thing group).
+ Index search queries.
+ [Device provisioning](iot-provision.md).
+ [AWS IoT Device Defender audit](https://docs.aws.amazon.com/iot-device-defender/latest/devguide/device-defender-audit.html) reports.