This is the new *CloudFormation Template Reference Guide*. Please update your bookmarks and links. For help getting started with CloudFormation, see the [AWS CloudFormation User Guide](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/Welcome.html).

# AWS::ApiGateway::ApiKey
<a name="aws-resource-apigateway-apikey"></a>

The `AWS::ApiGateway::ApiKey` resource creates a unique key that you can distribute to clients who are executing API Gateway `Method` resources that require an API key. To specify which API key clients must use, map the API key with the `RestApi` and `Stage` resources that include the methods that require a key. 

## Syntax
<a name="aws-resource-apigateway-apikey-syntax"></a>

To declare this entity in your CloudFormation template, use the following syntax:

### JSON
<a name="aws-resource-apigateway-apikey-syntax.json"></a>

```
{
  "Type" : "AWS::ApiGateway::ApiKey",
  "Properties" : {
      "[CustomerId](#cfn-apigateway-apikey-customerid)" : String,
      "[Description](#cfn-apigateway-apikey-description)" : String,
      "[Enabled](#cfn-apigateway-apikey-enabled)" : Boolean,
      "[GenerateDistinctId](#cfn-apigateway-apikey-generatedistinctid)" : Boolean,
      "[Name](#cfn-apigateway-apikey-name)" : String,
      "[StageKeys](#cfn-apigateway-apikey-stagekeys)" : [ StageKey, ... ],
      "[Tags](#cfn-apigateway-apikey-tags)" : [ Tag, ... ],
      "[Value](#cfn-apigateway-apikey-value)" : String
    }
}
```

### YAML
<a name="aws-resource-apigateway-apikey-syntax.yaml"></a>

```
Type: AWS::ApiGateway::ApiKey
Properties:
  [CustomerId](#cfn-apigateway-apikey-customerid): String
  [Description](#cfn-apigateway-apikey-description): String
  [Enabled](#cfn-apigateway-apikey-enabled): Boolean
  [GenerateDistinctId](#cfn-apigateway-apikey-generatedistinctid): Boolean
  [Name](#cfn-apigateway-apikey-name): String
  [StageKeys](#cfn-apigateway-apikey-stagekeys): 
    - StageKey
  [Tags](#cfn-apigateway-apikey-tags): 
    - Tag
  [Value](#cfn-apigateway-apikey-value): String
```

## Properties
<a name="aws-resource-apigateway-apikey-properties"></a>

`CustomerId`  <a name="cfn-apigateway-apikey-customerid"></a>
An AWS Marketplace customer identifier, when integrating with the AWS SaaS Marketplace.  
*Required*: No  
*Type*: String  
*Update requires*: [No interruption](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-updating-stacks-update-behaviors.html#update-no-interrupt)

`Description`  <a name="cfn-apigateway-apikey-description"></a>
The description of the ApiKey.  
*Required*: No  
*Type*: String  
*Update requires*: [No interruption](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-updating-stacks-update-behaviors.html#update-no-interrupt)

`Enabled`  <a name="cfn-apigateway-apikey-enabled"></a>
Specifies whether the ApiKey can be used by callers.  
*Required*: No  
*Type*: Boolean  
*Update requires*: [No interruption](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-updating-stacks-update-behaviors.html#update-no-interrupt)

`GenerateDistinctId`  <a name="cfn-apigateway-apikey-generatedistinctid"></a>
Specifies whether (`true`) or not (`false`) the key identifier is distinct from the created API key value. This parameter is deprecated and should not be used.  
*Required*: No  
*Type*: Boolean  
*Update requires*: [Replacement](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-updating-stacks-update-behaviors.html#update-replacement)

`Name`  <a name="cfn-apigateway-apikey-name"></a>
A name for the API key. If you don't specify a name, CloudFormation generates a unique physical ID and uses that ID for the API key name. For more information, see [Name Type](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-name.html).  
If you specify a name, you cannot perform updates that require replacement of this resource. You can perform updates that require no or some interruption. If you must replace the resource, specify a new name. 
*Required*: No  
*Type*: String  
*Update requires*: [Replacement](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-updating-stacks-update-behaviors.html#update-replacement)

`StageKeys`  <a name="cfn-apigateway-apikey-stagekeys"></a>
DEPRECATED FOR USAGE PLANS - Specifies stages associated with the API key.  
*Required*: No  
*Type*: Array of [StageKey](aws-properties-apigateway-apikey-stagekey.md)  
*Update requires*: [No interruption](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-updating-stacks-update-behaviors.html#update-no-interrupt)

`Tags`  <a name="cfn-apigateway-apikey-tags"></a>
The key-value map of strings. The valid character set is [a-zA-Z\$1-=.\$1:/]. The tag key can be up to 128 characters and must not start with `aws:`. The tag value can be up to 256 characters.  
*Required*: No  
*Type*: Array of [Tag](aws-properties-apigateway-apikey-tag.md)  
*Update requires*: [No interruption](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-updating-stacks-update-behaviors.html#update-no-interrupt)

`Value`  <a name="cfn-apigateway-apikey-value"></a>
Specifies a value of the API key.  
*Required*: No  
*Type*: String  
*Update requires*: [Replacement](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-updating-stacks-update-behaviors.html#update-replacement)

## Return values
<a name="aws-resource-apigateway-apikey-return-values"></a>

### Ref
<a name="aws-resource-apigateway-apikey-return-values-ref"></a>

When you pass the logical ID of this resource to the intrinsic `Ref` function, `Ref` returns the API key ID, such as `m2m1k7sybf`.

For more information about using the `Ref` function, see [https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/intrinsic-function-reference-ref.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/intrinsic-function-reference-ref.html).

### Fn::GetAtt
<a name="aws-resource-apigateway-apikey-return-values-fn--getatt"></a>

The `Fn::GetAtt` intrinsic function returns a value for a specified attribute of this type. The following are the available attributes and sample return values.

For more information about using the `Fn::GetAtt` intrinsic function, see [https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/intrinsic-function-reference-getatt.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/intrinsic-function-reference-getatt.html).

#### 
<a name="aws-resource-apigateway-apikey-return-values-fn--getatt-fn--getatt"></a>

`APIKeyId`  <a name="APIKeyId-fn::getatt"></a>
The ID for the API key. For example: `abc123`.

## Examples
<a name="aws-resource-apigateway-apikey--examples"></a>



### API Key
<a name="aws-resource-apigateway-apikey--examples--API_Key"></a>

The following example creates an API key and associates it with the `Test` stage of the `TestAPIDeployment` deployment. To ensure that CloudFormation creates the stage and deployment (which are declared elsewhere in the same template) before the API key, the example adds an explicit dependency on the deployment and stage. Without this dependency, CloudFormation might create the API key first, which would cause the association to fail because the deployment and stage wouldn't exist.

#### JSON
<a name="aws-resource-apigateway-apikey--examples--API_Key--json"></a>

```
{
    "ApiKey": {
        "Type": "AWS::ApiGateway::ApiKey",
        "DependsOn": [
            "TestAPIDeployment",
            "Test"
        ],
        "Properties": {
            "Name": "TestApiKey",
            "Description": "CloudFormation API Key V1",
            "Enabled": true,
            "StageKeys": [
                {
                    "RestApiId": {
                        "Ref": "RestApi"
                    },
                    "StageName": "Test"
                }
            ]
        }
    }
}
```

#### YAML
<a name="aws-resource-apigateway-apikey--examples--API_Key--yaml"></a>

```
ApiKey:
  Type: 'AWS::ApiGateway::ApiKey'
  DependsOn:
    - TestAPIDeployment
    - Test
  Properties:
    Name: TestApiKey
    Description: CloudFormation API Key V1
    Enabled: true
    StageKeys:
      - RestApiId: !Ref RestApi
        StageName: Test
```

## See also
<a name="aws-resource-apigateway-apikey--seealso"></a>
+ [apikey:create](https://docs.aws.amazon.com/apigateway/latest/api/API_CreateApiKey.html) in the *Amazon API Gateway REST API Reference*



# AWS::ApiGateway::ApiKey StageKey
<a name="aws-properties-apigateway-apikey-stagekey"></a>

`StageKey` is a property of the [AWS::ApiGateway::ApiKey](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-apikey.html) resource that specifies the stage to associate with the API key. This association allows only clients with the key to make requests to methods in that stage.

## Syntax
<a name="aws-properties-apigateway-apikey-stagekey-syntax"></a>

To declare this entity in your CloudFormation template, use the following syntax:

### JSON
<a name="aws-properties-apigateway-apikey-stagekey-syntax.json"></a>

```
{
  "[RestApiId](#cfn-apigateway-apikey-stagekey-restapiid)" : String,
  "[StageName](#cfn-apigateway-apikey-stagekey-stagename)" : String
}
```

### YAML
<a name="aws-properties-apigateway-apikey-stagekey-syntax.yaml"></a>

```
  [RestApiId](#cfn-apigateway-apikey-stagekey-restapiid): String
  [StageName](#cfn-apigateway-apikey-stagekey-stagename): String
```

## Properties
<a name="aws-properties-apigateway-apikey-stagekey-properties"></a>

`RestApiId`  <a name="cfn-apigateway-apikey-stagekey-restapiid"></a>
The string identifier of the associated RestApi.  
*Required*: No  
*Type*: String  
*Update requires*: [No interruption](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-updating-stacks-update-behaviors.html#update-no-interrupt)

`StageName`  <a name="cfn-apigateway-apikey-stagekey-stagename"></a>
The stage name associated with the stage key.  
*Required*: No  
*Type*: String  
*Update requires*: [No interruption](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-updating-stacks-update-behaviors.html#update-no-interrupt)

## See also
<a name="aws-properties-apigateway-apikey-stagekey--seealso"></a>
+ [stageKeys](https://docs.aws.amazon.com/apigateway/latest/api/API_CreateApiKey.html#stageKeys) in the *Amazon API Gateway REST API Reference*



# AWS::ApiGateway::ApiKey Tag
<a name="aws-properties-apigateway-apikey-tag"></a>

An array of key-value pairs to apply to this resource.

For more information, see [Tag](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-resource-tags.html).

## Syntax
<a name="aws-properties-apigateway-apikey-tag-syntax"></a>

To declare this entity in your CloudFormation template, use the following syntax:

### JSON
<a name="aws-properties-apigateway-apikey-tag-syntax.json"></a>

```
{
  "[Key](#cfn-apigateway-apikey-tag-key)" : String,
  "[Value](#cfn-apigateway-apikey-tag-value)" : String
}
```

### YAML
<a name="aws-properties-apigateway-apikey-tag-syntax.yaml"></a>

```
  [Key](#cfn-apigateway-apikey-tag-key): String
  [Value](#cfn-apigateway-apikey-tag-value): String
```

## Properties
<a name="aws-properties-apigateway-apikey-tag-properties"></a>

`Key`  <a name="cfn-apigateway-apikey-tag-key"></a>
A string you can use to assign a value. The combination of tag keys and values can help you organize and categorize your resources.  
*Required*: Yes  
*Type*: String  
*Minimum*: `1`  
*Maximum*: `128`  
*Update requires*: [No interruption](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-updating-stacks-update-behaviors.html#update-no-interrupt)

`Value`  <a name="cfn-apigateway-apikey-tag-value"></a>
The value for the specified tag key.  
*Required*: Yes  
*Type*: String  
*Maximum*: `256`  
*Update requires*: [No interruption](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-updating-stacks-update-behaviors.html#update-no-interrupt)