# Tag your AWS IoT SiteWise resources
<a name="tag-resources"></a>

Tagging your AWS IoT SiteWise resources provides a powerful way to categorize, manage, and retrieve organizational assets efficiently. By assigning tags, which consist of key-value pairs, you can attach descriptive metadata to your resources. The metadata from tags can be used to streamline operations. For example, in a wind farm scenario, tags allow you to label turbines with specific attributes like location, capacity, and operational status, enabling quick identification and management within AWS IoT SiteWise.

Integrating tags with AWS Identity and Access Management (IAM) policies enhances security and operational control by defining conditional access rules. This means you can specify that only users with certain tags. For example, only those tagged with a certain role or department, can access or modify particular resources.

# Use tags in AWS IoT SiteWise
<a name="tag-basics"></a>

Use tags to categorize your AWS IoT SiteWise resources by purpose, owner, environment, or any other classification for your use case. When you have many resources of the same type, you can quickly identify a specific resource based on its tags.

Each tag is made up of a key and an optional value that you specify. For example, you can establish a series of tags for your asset models to track them according to the industrial processes they support. It's recommended to develop a tailored set of tag keys for each type of resource you manage. Using a consistent set of tag keys can makes it easier manage resources.

## Tag with the AWS Management Console
<a name="tags-console"></a>

The **Tag Editor** in the AWS Management Console provides a central, unified way for you to create and manage your tags for resources from all AWS services. For more information, see [Getting started with Tag Editor](https://docs.aws.amazon.com/tag-editor/latest/userguide/gettingstarted.html) in the *Tagging AWS Resources and Tag Editor User Guide*.

## Tag with the AWS IoT SiteWise API
<a name="tags-api"></a>

The AWS IoT SiteWise API also uses tags. Before you create tags, be aware of tagging restrictions. For more information, see [Tag naming and usage conventions](https://docs.aws.amazon.com/general/latest/gr/aws_tagging.html#tag-conventions) in the *AWS General Reference*.
+ To add tags when you create a resource, define them in the `tags` property of the resource.
+ To add tags to an existing resource, or to update tag values, use the [TagResource](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_TagResource.html) operation.
+ To remove tags from a resource, use the [UntagResource](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_UntagResource.html) operation.
+ To retrieve the tags that are associated with a resource, use the [ListTagsForResource](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_ListTagsForResource.html) operation, or describe the resource and inspect its `tags` property.

The following table lists resources you can tag using the AWS IoT SiteWise API and their corresponding `Create` and `Describe` operations.


**Taggable AWS IoT SiteWise resources**  

| Resource | Create operation | Describe operation | 
| --- | --- | --- | 
| Asset model or component model | [CreateAssetModel](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_CreateAssetModel.html) | [DescribeAssetModel](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_DescribeAssetModel.html) | 
| Asset | [CreateAsset](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_CreateAsset.html) | [DescribeAsset](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_DescribeAsset.html) | 
| SiteWise Edge gateway | [CreateGateway](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_CreateGateway.html) | [DescribeGateway](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_DescribeGateway.html) | 
| Portal | [CreatePortal](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_CreatePortal.html) | [DescribePortal](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_DescribePortal.html) | 
| Project | [CreateProject](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_CreateProject.html) | [DescribeProject](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_DescribeProject.html) | 
| Dashboard | [CreateDashboard](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_CreateDashboard.html) | [DescribeDashboard](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_DescribeDashboard.html) | 
| Access policy | [CreateAccessPolicy](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_CreateAccessPolicy.html) | [DescribeAccessPolicy](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_DescribeAccessPolicy.html) | 
| Time series | [BatchPutAssetPropertyValue](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_BatchPutAssetPropertyValue.html) | [DescribeTimeSeries](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_DescribeTimeSeries.html) | 

For `[BatchPutAssetPropertyValue](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_BatchPutAssetPropertyValue.html)`, you can configure your data sources to send industrial data to AWS IoT SiteWise before you create asset models and assets. AWS IoT SiteWise automatically creates data streams to receive streams of raw data from your equipment. For more information, see [Managing data ingestion](https://docs.aws.amazon.com//iot-sitewise/latest/userguide/data-streams.html).

Use the following operations to view and manage tags for resources that support tagging:
+ [TagResource](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_TagResource.html) – Adds tags to a resource, or updates an existing tag's value.
+ [ListTagsForResource](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_ListTagsForResource.html) – Lists the tags for a resource.
+ [UntagResource](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_UntagResource.html) – Removes tags from a resource.

Add or remove tags from a resource at any time. To update the value of an existing tag key, add a new tag with the same key and your desired new value to the resource. This action replaces the old value with the new one. While it's possible to assign an empty string as a tag value, you can't assign a null value.

Deleting a resource also removes any tags linked to it.

# Use tags with IAM policies
<a name="tags-iam"></a>

Use resource tags in your IAM policies to control user access and permissions. For example, policies can allow users to only create resources that have a specific tag attached. Policies can also restrict users from creating or modifying resources that have certain tags.

**Note**  
If you use tags to allow or deny users' access to resources, you should deny users the ability to add or remove those tags for the same resources. Otherwise, a user could bypass your restrictions and gain access to a resource by modifying its tags.

You can use the following condition context keys and values in the `Condition` element (also called the `Condition` block) of a policy statement.

`aws:ResourceTag/tag-key: tag-value`  
Allow or deny actions on resources with specific tags.

`aws:RequestTag/tag-key: tag-value`  
Require that a specific tag be used (or not used) when creating or modifying a taggable resource.

`aws:TagKeys: [tag-key, ...]`  
Require that a specific set of tag keys be used (or not used) when creating or modifying a taggable resource.

**Note**  
The condition context keys and values in an IAM policy apply only to actions that have a taggable resource as a required parameter. For example, you can set tag-based conditional access for [ListAssets](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_ListAssets.html). You can't set tag-based conditional access on [PutLoggingOptions](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_PutLoggingOptions.html) because no taggable resource is referenced in the request.

For more information, see [Controlling access to AWS resources using resource tags](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_tags.html) and [IAM JSON policy reference](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies.html) in the *IAM User Guide*.

**Example IAM policies using tags**
+ [View AWS IoT SiteWise assets based on tags](security_iam_id-based-policy-examples.md#security_iam_id-based-policy-examples-view-asset-tags)