# Tagging your API Gateway resources Tagging A *tag* is a metadata label that you assign or that AWS assigns to an AWS resource. Each tag has two parts: + A *tag key* (for example, `CostCenter`, `Environment`, or `Project`). Tag keys are case sensitive. + An optional field known as a *tag value* (for example, `111122223333` or `Production`). Omitting the tag value is the same as using an empty string. Like tag keys, tag values are case-sensitive. Tags help you do the following: + Control access to your resources based on the tags that are assigned to them. You control access by specifying tag keys and values in the conditions for an AWS Identity and Access Management (IAM) policy. For more information about tag-based access control, see [Controlling Access Using Tags](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_tags.html) in the *IAM User Guide*. + Track your AWS costs. You activate these tags on the AWS Billing and Cost Management dashboard. AWS uses the tags to categorize your costs and deliver a monthly cost allocation report to you. For more information, see [Use Cost Allocation Tags](https://docs.aws.amazon.com/awsaccountbilling/latest/aboutv2/cost-alloc-tags.html) in the [AWS Billing User Guide](https://docs.aws.amazon.com/awsaccountbilling/latest/aboutv2/). + Identify and organize your AWS resources. Many AWS services support tagging, so you can assign the same tag to resources from different services to indicate that the resources are related. For example, you could assign the same tag to an API Gateway stage that you assign to a CloudWatch Events rule. For tips on using tags, see the whitepaper [AWS Tagging Strategies](https://docs.aws.amazon.com/whitepapers/latest/tagging-best-practices/tagging-best-practices.html). The following sections provide more information about tags for Amazon API Gateway. **Topics** + [ # API Gateway resources that can be tagged ](apigateway-tagging-supported-resources.md) + [ # Using tags to control access to API Gateway REST API resources ](apigateway-tagging-iam-policy.md) # API Gateway resources that can be tagged Tags can be set on the following HTTP API or WebSocket API resources in the [Amazon API Gateway V2 API](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/): + `Api` + `DomainName` + `Stage` + `VpcLink` In addition, tags can be set on the following REST API resources in the [Amazon API Gateway V1 API](https://docs.aws.amazon.com/apigateway/latest/api/API_Operations.html): + `ApiKey` + `ClientCertificate` + `DomainName` + `DomainNameAccessAssociation` + `RestApi` + `Stage` + `UsagePlan` + `VpcLink` Tags cannot be set directly on other resources. However, in the [Amazon API Gateway V1 API](https://docs.aws.amazon.com/apigateway/latest/api/API_Operations.html), child resources inherit the tags that are set on parent resources. For example: + If a tag is set on a `RestApi` resource, that tag is inherited by the following child resources of that `RestApi` for [Attribute-based access control](https://docs.aws.amazon.com/IAM/latest/UserGuide/introduction_attribute-based-access-control.html): + `Authorizer` + `Deployment` + `Documentation` + `GatewayResponse` + `Integration` + `Method` + `Model` + `Resource` + `ResourcePolicy` + `Setting` + `Stage` + If a tag is set on a `DomainName`, that tag is inherited by any `BasePathMapping`, `ApiMapping`, and `RoutingRule` resources under it. + If a tag is set on a `UsagePlan`, that tag is inherited by any `UsagePlanKey` resources under it. **Note** Tag inheritance applies only to [attribute-based access control](https://docs.aws.amazon.com/IAM/latest/UserGuide/introduction_attribute-based-access-control.html). For example, you can't use inherited tags to monitor costs in AWS Cost Explorer. To use tags for cost allocation, we recommend that you create tags on child resources, such as the `Stage` resource. API Gateway doesn't return inherited tags when you call [GetTags](https://docs.aws.amazon.com/cli/latest/reference/apigateway/get-tags.html) for a resource. ## Tag inheritance in the Amazon API Gateway V1 API Previously it was only possible to set tags on stages. Now that you can also set them on other resources, a `Stage` can receive a tag two ways: + The tag can be set directly on the `Stage`. + The stage can inherit the tag from its parent `RestApi`. If a stage receives a tag both ways, the tag that was set directly on the stage takes precedence. For example, suppose a stage inherits the following tags from its parent REST API: ``` { 'foo': 'bar', 'x':'y' } ``` Suppose it also has the following tags set on it directly: ``` { 'foo': 'bar2', 'hello': 'world' } ``` The net effect would be for the stage to have the following tags, with the following values: ``` { 'foo': 'bar2', 'hello': 'world' 'x':'y' } ``` ## Tag restrictions and usage conventions The following restrictions and usage conventions apply to using tags with API Gateway resources: + Each resource can have a maximum of 50 tags. + For each resource, each tag key must be unique, and each tag key can have only one value. + The maximum tag key length is 128 Unicode characters in UTF-8. + The maximum tag value length is 256 Unicode characters in UTF-8. + Allowed characters for keys and values are letters, numbers, spaces representable in UTF-8, and the following characters:*** . : \$1 = @ \$1 / -*** (hyphen). Amazon EC2 resources allow any characters. + Tag keys and values are case-sensitive. As a best practice, decide on a strategy for capitalizing tags, and consistently implement that strategy across all resource types. For example, decide whether to use `Costcenter`, `costcenter`, or `CostCenter`, and use the same convention for all tags. Avoid using similar tags with inconsistent case treatment. + The `aws:` prefix is prohibited for tags; it's reserved for AWS use. You can't edit or delete tag keys or values with this prefix. Tags with this prefix do not count against your tags per resource limit. # Using tags to control access to API Gateway REST API resources Attribute-based access control Conditions in AWS Identity and Access Management policies are part of the syntax that you use to specify permissions to API Gateway resources. For details about specifying IAM policies, see [Control access to a REST API with IAM permissions](permissions.md). In API Gateway, resources can have tags, and some actions can include tags. When you create an IAM policy, you can use tag condition keys to control: + Which users can perform actions on an API Gateway resource, based on tags that the resource already has. + Which tags can be passed in an action's request. + Whether specific tag keys can be used in a request. Using tags for attribute-based access control can allow for finer control than API-level control, as well as more dynamic control than resource-based access control. IAM policies can be created that allow or disallow an operation based on tags provided in the request (request tags), or tags on the resource that is being operated on (resource tags). In general, resource tags are for resources that already exist. Request tags are for when you're creating new resources. For the complete syntax and semantics of tag condition keys, see [Controlling Access Using Tags](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_tags.html) in the *IAM User Guide*. The following examples demonstrate how to specify tag conditions in policies for API Gateway users. ## Limit actions based on resource tags The following example policy grants users permission to perform all actions on all resources, as long as those resources don't have the tag `Environment` with a value of `prod`. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "apigateway:*", "Resource": "*" }, { "Effect": "Deny", "Action": [ "apigateway:*" ], "Resource": "*", "Condition": { "StringEquals": { "aws:ResourceTag/Environment": "prod" } } } ] } ``` ------ ## Allow actions based on resource tags The following example policy allows users to perform all actions on API Gateway resources, as long as the resources have the tag `Environment` with a value of `Development`. The `Deny` statement prevents the user from changing the value of the `Environment` tag. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "ConditionallyAllow", "Effect": "Allow", "Action": [ "apigateway:*" ], "Resource": [ "arn:aws:apigateway:*::*" ], "Condition": { "StringEquals": { "aws:ResourceTag/Environment": "Development" } } }, { "Sid": "AllowTagging", "Effect": "Allow", "Action": [ "apigateway:*" ], "Resource": [ "arn:aws:apigateway:*::/tags/*" ] }, { "Sid": "DenyChangingTag", "Effect": "Deny", "Action": [ "apigateway:*" ], "Resource": [ "arn:aws:apigateway:*::/tags/*" ], "Condition": { "ForAnyValue:StringEquals": { "aws:TagKeys": "Environment" } } } ] } ``` ------ ## Deny tagging operations The following example policy allows a user to perform all API Gateway actions, except for changing tags. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "apigateway:*" ], "Resource": [ "*" ] }, { "Effect": "Deny", "Action": [ "apigateway:*" ], "Resource": "arn:aws:apigateway:*::/tags*" } ] } ``` ------ ## Allow tagging operations The following example policy allows a user to get all API Gateway resources, and change tags for those resources. To get the tags for a resource, the user must have `GET` permissions for that resource. To update the tags for a resource, the user must have `PATCH` permissions for that resource. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "apigateway:GET", "apigateway:PUT", "apigateway:POST", "apigateway:DELETE" ], "Resource": [ "arn:aws:apigateway:*::/tags/*" ] }, { "Effect": "Allow", "Action": [ "apigateway:GET", "apigateway:PATCH" ], "Resource": [ "arn:aws:apigateway:*::*" ] } ] } ``` ------