How to Rename AWS Resource Tag Keys Using the Resource Groups Tagging API?

Introduction

AWS resource tags are key-value pairs used for cost allocation, access control, automation, and organizational visibility. Over time, inconsistent tag key naming conventions can accumulate — especially in environments built manually through the AWS console, or where tags were applied via scripting from spreadsheets during migration.

Common scenarios include:

• Spaces in keys: application name → application-name
• Case variations: Application-Name or APPLICATION-NAME → application-name

AWS treats each of these as completely separate, unique tag keys. AWS recommends using all-lowercase with hyphens as separators for tag key names. A Tag Policy can enforce casing going forward, but it will not retroactively fix existing variant keys — that requires the remediation of the existing keys.

Important: You cannot rename a tag key in place, as documented here:

You can't rename a tag key, but you can delete a tag and create a tag with a new name to replace the original tag key.

GUI Options

For a small number of resources, you can add the new key and remove the old one directly in the console:

• AWS Tag Editor — search by tag key, select resources, Manage tags of selected resources. Single-account.
• AWS Resource Explorer — search with tag filters, select resources, Actions → Manage tags. Single-account for editing tags; supports multi-account search with Organizational View.

CLI Approach

For larger estates, multi-account environments, or when you need to preserve existing tag values per resource, a programmatic approach is more efficient. You can use Resource Groups Tagging API (CLI) to handle tag renaming at scale.

Note: The CLI commands below are examples to demonstrate the approach. You can adapt them into your own scripts, automation pipelines, or SDK-based tooling (Python/Boto3, etc.) as suits your environment.

In the following example, we find resources tagged with application name (space-separated) and rename the key to application-name (hyphen-separated) — aligning with the AWS-recommended naming convention while preserving each resource's existing value.

Step 1 — Export Resources with the Old Tag Key to CSV

Use GetResources to find all resources with the incorrect tag key and export the ARN and current value to a CSV file:

aws resourcegroupstaggingapi get-resources \
  --region us-east-1 \
  --tag-filters 'Key=application name' \
  --output json | jq -r '
  .ResourceTagMappingList[] as $r
  | $r.Tags[]
  | select(.Key == "application name")
  | [$r.ResourceARN, .Value] | @csv' > tag-rename-export.csv

Sample Output (ARN + existing value):

"arn:aws:ec2:us-east-1:123456789012:instance/i-abc123","MyApp"
"arn:aws:ec2:us-east-1:123456789012:volume/vol-def456","PayrollSystem"

If you want to scope to specific resource types, add the --resource-type-filters parameter (e.g., ec2:instance ec2:snapshot ec2:volume).

Pagination: The AWS CLI handles pagination automatically. It follows PaginationToken internally and returns the complete result with matched resources. For more information, see AWS CLI Pagination.

Step 2 — Review the Export (Dry-Run)

Before making changes, review the CSV to validate:

• The correct resources are captured
• Values are accurate and should be preserved
• No unexpected entries exist (e.g., glob characters or malformed ARNs)

This step serves as your dry-run — no changes are made until Steps 3 and 5.

Important: Before modifying tags, confirm there are no dependencies on the existing tag key — such as tag-based automation (Auto Scaling, Backup Plans), application grouping, or IAM/SCP policies that reference it. When remediating, it's recommended to apply the new tag before removing the old one.

Step 3 — Apply the New Tag Key with Preserved Values

Iterate through the CSV and create the new tag (corrected key name) on each resource, preserving the original value:

while IFS=, read -r arn value; do
  arn=$(echo "$arn" | tr -d '"')
  value=$(echo "$value" | tr -d '"')
  aws resourcegroupstaggingapi tag-resources \
    --region us-east-1 \
    --resource-arn-list "$arn" \
    --tags "application-name=$value" \
    --output json
done < tag-rename-export.csv

Step 4 — Validate the New Tags

After applying new tags, verify that the new key exists on the resources before removing the old key. Export the resources carrying the new key and compare against the original export:

aws resourcegroupstaggingapi get-resources \
  --region us-east-1 \
  --tag-filters 'Key=application-name' \
  --output json | jq -r '
  .ResourceTagMappingList[] as $r
  | $r.Tags[]
  | select(.Key == "application-name")
  | [$r.ResourceARN, .Value] | @csv' > tag-rename-verify.csv

Compare tag-rename-verify.csv against the original tag-rename-export.csv to confirm:

• The same ARNs are present
• The values are correctly preserved under the new key

Once validated, proceed with Step 5 (removing old tags).

Step 5 — Remove the Old Tag Key

Once the new tags are validated, remove the old tag key:

while IFS=, read -r arn value; do
  arn=$(echo "$arn" | tr -d '"')
  aws resourcegroupstaggingapi untag-resources \
    --region us-east-1 \
    --resource-arn-list "$arn" \
    --tag-keys "application name" \
    --output json
done < tag-rename-export.csv

Additional Tag Keys or Variants

If you have multiple tag keys to rename (e.g., case variants of the same logical key), repeat Steps 1–5 for each variant. Update the --tag-filters, --tags, and --tag-keys values accordingly in each iteration.

The API call operates per region, per account. For multi-region or multi-account environments, you can extend these commands into your existing automation or scripting workflows as needed.

Considerations

• Resource types: The Resource Groups Tagging API supports most AWS resource types — including EC2, S3, RDS, and Lambda. See the full list of supported services to confirm coverage for your specific resources.
• API Limits: TagResources and UntagResources are limited to 5 calls per second and GetResources to 15 calls per second. See Resource Groups and Tagging endpoints and quotas. Configure AWS CLI retries as needed.
• Tag policies: If you use tag policies, ensure the new tag key conforms to the defined policy. Tag policies enforce case treatment on supplied tags but do not prevent resources from being created without tags — use SCPs for that.
• Cost allocation tags: If the old tag key was activated as a cost allocation tag, you must activate the new key in Billing → Cost allocation tags. Historical cost data remains under the old key name — it is not retroactively corrected.

Conclusion

While tag key renaming is not supported directly, the Resource Groups Tagging API provides a programmatic approach to bulk rename tags by exporting, re-tagging, and removing old keys. By following the export → validate → apply → verify → remove workflow, you can standardize tag naming conventions across your environment safely and efficiently.

For ongoing governance after remediation, consider deploying AWS Organizations Tag Policies (to enforce case treatment on future tags) and Service Control Policies (to deny resource creation without required tags) — ensuring the inconsistencies don't recur.

Resources

• AWS Tag Editor — Editing Tags
• AWS CLI Automatic Pagination
• Supported Resource Types for Tagging API
• AWS Organizations Tag Policies
• AWS Resource Explorer — Manage Tags
• Implement Tagging Strategy with Tag Policies and SCPs