# AWS::Serverless::Api
<a name="sam-resource-api"></a>

Creates a collection of Amazon API Gateway resources and methods that can be invoked through HTTPS endpoints.

An [AWS::Serverless::Api](#sam-resource-api) resource need not be explicitly added to a AWS Serverless Application Definition template. A resource of this type is implicitly created from the union of Api events defined on [AWS::Serverless::Function](sam-resource-function.md) resources defined in the template that do not refer to an [AWS::Serverless::Api](#sam-resource-api) resource.

An [AWS::Serverless::Api](#sam-resource-api) resource should be used to define and document the API using OpenApi, which provides more ability to configure the underlying Amazon API Gateway resources.

We recommend that you use CloudFormation hooks or IAM policies to verify that API Gateway resources have authorizers attached to them to control access to them.

For more information about using CloudFormation hooks, see [Registering hooks](https://docs.aws.amazon.com/cloudformation-cli/latest/userguide/registering-hook-python.html) in the *CloudFormation CLI user guide* and the [apigw-enforce-authorizer](https://github.com/aws-cloudformation/aws-cloudformation-samples/tree/main/hooks/python-hooks/apigw-enforce-authorizer/) GitHub repository.

For more information about using IAM policies, see [Require that API routes have authorization](https://docs.aws.amazon.com/apigateway/latest/developerguide/security_iam_id-based-policy-examples.html#security_iam_id-based-policy-examples-require-authorization) in the *API Gateway Developer Guide*.

**Note**  
When you deploy to AWS CloudFormation, AWS SAM transforms your AWS SAM resources into CloudFormation resources. For more information, see [Generated CloudFormation resources for AWS SAM](sam-specification-generated-resources.md).

## Syntax
<a name="sam-resource-api-syntax"></a>

To declare this entity in your AWS Serverless Application Model (AWS SAM) template, use the following syntax.

### YAML
<a name="sam-resource-api-syntax.yaml"></a>

```
Type: AWS::Serverless::Api
Properties:
  [AccessLogSetting](#sam-api-accesslogsetting): [AccessLogSetting](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-stage.html#cfn-apigateway-stage-accesslogsetting)
  AlwaysDeploy: Boolean
  [ApiKeySourceType](#sam-api-apikeysourcetype): String
  [Auth](#sam-api-auth): ApiAuth
  [BinaryMediaTypes](#sam-api-binarymediatypes): List
  [CacheClusterEnabled](#sam-api-cacheclusterenabled): Boolean
  [CacheClusterSize](#sam-api-cacheclustersize): String
  [CanarySetting](#sam-api-canarysetting): [CanarySetting](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-stage.html#cfn-apigateway-stage-canarysetting)
  [Cors](#sam-api-cors): String | CorsConfiguration
  [DefinitionBody](#sam-api-definitionbody): JSON
  [DefinitionUri](#sam-api-definitionuri): String | ApiDefinition
  [Description](#sam-api-description): String
  [DisableExecuteApiEndpoint](#sam-api-disableexecuteapiendpoint): Boolean
  [Domain](#sam-api-domain): DomainConfiguration
  [EndpointConfiguration](#sam-api-endpointconfiguration): EndpointConfiguration
  [FailOnWarnings](#sam-api-failonwarnings): Boolean
  [GatewayResponses](#sam-api-gatewayresponses): Map
  MergeDefinitions: Boolean
  [MethodSettings](#sam-api-methodsettings): MethodSettings
  [MinimumCompressionSize](#sam-api-minimumcompressionsize): Integer
  [Mode](#sam-api-mode): String
  [Models](#sam-api-models): Map
  [Name](#sam-api-name): String
  [OpenApiVersion](#sam-api-openapiversion): String
  PropagateTags: Boolean
  [Policy](#sam-api-policy): JSON
  [StageName](#sam-api-stagename): String
  [Tags](#sam-api-tags): Map
  [TracingEnabled](#sam-api-tracingenabled): Boolean
  [Variables](#sam-api-variables): Map
```

## Properties
<a name="sam-resource-api-properties"></a>

 `AccessLogSetting`   <a name="sam-api-accesslogsetting"></a>
Configures Access Log Setting for a stage.  
*Type*: [AccessLogSetting](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-stage.html#cfn-apigateway-stage-accesslogsetting)  
*Required*: No  
*CloudFormation compatibility*: This property is passed directly to the `[AccessLogSetting](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-stage.html#cfn-apigateway-stage-accesslogsetting)` property of an `AWS::ApiGateway::Stage` resource.

 `AlwaysDeploy`   <a name="sam-api-alwaysdeploy"></a>
Always deploys the API, even when no changes to the API have been detected.  
*Type*: Boolean  
*Required*: No  
*CloudFormation compatibility*: This property is unique to AWS SAM and doesn't have an CloudFormation equivalent.

 `ApiKeySourceType`   <a name="sam-api-apikeysourcetype"></a>
The source of the API key for metering requests according to a usage plan. Valid values are `HEADER` and `AUTHORIZER`.  
*Type*: String  
*Required*: No  
*CloudFormation compatibility*: This property is passed directly to the `[ApiKeySourceType](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-apikeysourcetype)` property of an `AWS::ApiGateway::RestApi` resource.

 `Auth`   <a name="sam-api-auth"></a>
Configure authorization to control access to your API Gateway API.  
For more information about configuring access using AWS SAM see [Control API access with your AWS SAM template](serverless-controlling-access-to-apis.md). For an example showing how to override a global authorizer, see [Override a global authorizer for your Amazon API Gateway REST API](sam-property-function-apifunctionauth.md#sam-property-function-apifunctionauth--examples--override).  
*Type*: [ApiAuth](sam-property-api-apiauth.md)  
*Required*: No  
*CloudFormation compatibility*: This property is unique to AWS SAM and doesn't have an CloudFormation equivalent.

 `BinaryMediaTypes`   <a name="sam-api-binarymediatypes"></a>
List of MIME types that your API could return. Use this to enable binary support for APIs.  
*Type*: List  
*Required*: No  
*CloudFormation compatibility*: This property is similar to the `[BinaryMediaTypes](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-binarymediatypes)` property of an `AWS::ApiGateway::RestApi` resource. The list of BinaryMediaTypes is added to both the CloudFormation resource and the OpenAPI document.

 `CacheClusterEnabled`   <a name="sam-api-cacheclusterenabled"></a>
Indicates whether caching is enabled for the stage. To cache responses, you must also set `CachingEnabled` to `true` under `MethodSettings`.  
*Type*: Boolean  
*Required*: No  
*CloudFormation compatibility*: This property is passed directly to the `[CacheClusterEnabled](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-stage.html#cfn-apigateway-stage-cacheclusterenabled)` property of an `AWS::ApiGateway::Stage` resource.

 `CacheClusterSize`   <a name="sam-api-cacheclustersize"></a>
The stage's cache cluster size.  
*Type*: String  
*Required*: No  
*CloudFormation compatibility*: This property is passed directly to the `[CacheClusterSize](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-stage.html#cfn-apigateway-stage-cacheclustersize)` property of an `AWS::ApiGateway::Stage` resource.

 `CanarySetting`   <a name="sam-api-canarysetting"></a>
Configure a canary setting to a stage of a regular deployment.  
*Type*: [CanarySetting](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-stage.html#cfn-apigateway-stage-canarysetting)  
*Required*: No  
*CloudFormation compatibility*: This property is passed directly to the `[CanarySetting](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-stage.html#cfn-apigateway-stage-canarysetting)` property of an `AWS::ApiGateway::Stage` resource.

 `Cors`   <a name="sam-api-cors"></a>
Manage Cross-origin resource sharing (CORS) for all your API Gateway APIs. Specify the domain to allow as a string or specify a dictionary with additional Cors configuration.   
CORS requires AWS SAM to modify your OpenAPI definition. Create an inline OpenAPI definition in the `DefinitionBody` to turn on CORS.
For more information about CORS, see [Enable CORS for an API Gateway REST API Resource](https://docs.aws.amazon.com/apigateway/latest/developerguide/how-to-cors.html) in the *API Gateway Developer Guide*.  
*Type*: String \$1 [CorsConfiguration](sam-property-api-corsconfiguration.md)  
*Required*: No  
*CloudFormation compatibility*: This property is unique to AWS SAM and doesn't have an CloudFormation equivalent.

 `DefinitionBody`   <a name="sam-api-definitionbody"></a>
OpenAPI specification that describes your API. If neither `DefinitionUri` nor `DefinitionBody` are specified, SAM will generate a `DefinitionBody` for you based on your template configuration.  
To reference a local OpenAPI file that defines your API, use the `AWS::Include` transform. To learn more, see [How AWS SAM uploads local files](deploy-upload-local-files.md).  
*Type*: JSON  
*Required*: No  
*CloudFormation compatibility*: This property is similar to the `[Body](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-body)` property of an `AWS::ApiGateway::RestApi` resource. If certain properties are provided, content may be inserted or modified into the DefinitionBody before being passed to CloudFormation. Properties include `Auth`, `BinaryMediaTypes`, `Cors`, `GatewayResponses`, `Models`, and an `EventSource` of type Api for a corresponding `AWS::Serverless::Function`.

 `DefinitionUri`   <a name="sam-api-definitionuri"></a>
Amazon S3 Uri, local file path, or location object of the the OpenAPI document defining the API. The Amazon S3 object this property references must be a valid OpenAPI file. If neither `DefinitionUri` nor `DefinitionBody` are specified, SAM will generate a `DefinitionBody` for you based on your template configuration.  
If a local file path is provided, the template must go through the workflow that includes the `sam deploy` or `sam package` command, in order for the definition to be transformed properly.  
Intrinsic functions are not supported in external OpenApi files referenced by `DefinitionUri`. Use instead the `DefinitionBody` property with the [Include Transform](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/create-reusable-transform-function-snippets-and-add-to-your-template-with-aws-include-transform.html) to import an OpenApi definition into the template.  
*Type*: String \$1 [ApiDefinition](sam-property-api-apidefinition.md)  
*Required*: No  
*CloudFormation compatibility*: This property is similar to the `[BodyS3Location](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-bodys3location)` property of an `AWS::ApiGateway::RestApi` resource. The nested Amazon S3 properties are named differently.

 `Description`   <a name="sam-api-description"></a>
A description of the Api resource.  
*Type*: String  
*Required*: No  
*CloudFormation compatibility*: This property is passed directly to the `[Description](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-description)` property of an `AWS::ApiGateway::RestApi` resource.

 `DisableExecuteApiEndpoint`   <a name="sam-api-disableexecuteapiendpoint"></a>
Specifies whether clients can invoke your API by using the default `execute-api` endpoint. By default, clients can invoke your API with the default `https://{api_id}.execute-api.{region}.amazonaws.com`. To require that clients use a custom domain name to invoke your API, specify `True`.  
*Type*: Boolean  
*Required*: No  
*CloudFormation compatibility*: This property is similar to the `[ DisableExecuteApiEndpoint](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-disableexecuteapiendpoint)` property of an `AWS::ApiGateway::RestApi` resource. It is passed directly to the `disableExecuteApiEndpoint` property of an `[ x-amazon-apigateway-endpoint-configuration](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-swagger-extensions-endpoint-configuration.html)` extension, which gets added to the ` [ Body](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-body)` property of an `AWS::ApiGateway::RestApi` resource.

 `Domain`   <a name="sam-api-domain"></a>
Configures a custom domain for this API Gateway API.  
*Type*: [DomainConfiguration](sam-property-api-domainconfiguration.md)  
*Required*: No  
*CloudFormation compatibility*: This property is unique to AWS SAM and doesn't have an CloudFormation equivalent.

 `EndpointConfiguration`   <a name="sam-api-endpointconfiguration"></a>
The endpoint type of a REST API.  
*Type*: [EndpointConfiguration](sam-property-api-endpointconfiguration.md)  
*Required*: No  
*CloudFormation compatibility*: This property is similar to the `[EndpointConfiguration](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-endpointconfiguration)` property of an `AWS::ApiGateway::RestApi` resource. The nested configuration properties are named differently.

 `FailOnWarnings`   <a name="sam-api-failonwarnings"></a>
Specifies whether to roll back the API creation (`true`) or not (`false`) when a warning is encountered. The default value is `false`.  
*Type*: Boolean  
*Required*: No  
*CloudFormation compatibility*: This property is passed directly to the `[FailOnWarnings](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-failonwarnings)` property of an `AWS::ApiGateway::RestApi` resource.

 `GatewayResponses`   <a name="sam-api-gatewayresponses"></a>
Configures Gateway Responses for an API. Gateway Responses are responses returned by API Gateway, either directly or through the use of Lambda Authorizers. For more information, see the documentation for the [Api Gateway OpenApi extension for Gateway Responses](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-swagger-extensions-gateway-responses.html).  
*Type*: Map  
*Required*: No  
*CloudFormation compatibility*: This property is unique to AWS SAM and doesn't have an CloudFormation equivalent.

 `MergeDefinitions`   <a name="sam-api-mergedefinitions"></a>
AWS SAM generates an OpenAPI specification from your API event source. Specify `true` to have AWS SAM merge this into the inline OpenAPI specification defined in your `AWS::Serverless::Api` resource. Specify `false` to not merge.  
`MergeDefinitions` requires the `DefinitionBody` property for `AWS::Serverless::Api` to be defined. `MergeDefinitions` is not compatible with the `DefinitionUri` property for `AWS::Serverless::Api`.  
*Default value*: `false`  
*Type*: Boolean  
*Required*: No  
*CloudFormation compatibility*: This property is unique to AWS SAM and doesn't have an CloudFormation equivalent.

 `MethodSettings`   <a name="sam-api-methodsettings"></a>
Configures all settings for API stage including Logging, Metrics, CacheTTL, Throttling.  
*Type*: List of [ MethodSetting](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-apigateway-stage-methodsetting.html)  
*Required*: No  
*CloudFormation compatibility*: This property is passed directly to the `[MethodSettings](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-stage.html#cfn-apigateway-stage-methodsettings)` property of an `AWS::ApiGateway::Stage` resource.

 `MinimumCompressionSize`   <a name="sam-api-minimumcompressionsize"></a>
Allow compression of response bodies based on client's Accept-Encoding header. Compression is triggered when response body size is greater than or equal to your configured threshold. The maximum body size threshold is 10 MB (10,485,760 Bytes). - The following compression types are supported: gzip, deflate, and identity.  
*Type*: Integer  
*Required*: No  
*CloudFormation compatibility*: This property is passed directly to the `[MinimumCompressionSize](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-minimumcompressionsize)` property of an `AWS::ApiGateway::RestApi` resource.

 `Mode`   <a name="sam-api-mode"></a>
This property applies only when you use OpenAPI to define your REST API. The `Mode` determines how API Gateway handles resource updates. For more information, see [Mode](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-mode) property of the [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html) resource type.  
*Valid values*: `overwrite` or `merge`  
*Type*: String  
*Required*: No  
*CloudFormation compatibility*: This property is passed directly to the `[Mode](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-mode)` property of an `AWS::ApiGateway::RestApi` resource.

 `Models`   <a name="sam-api-models"></a>
The schemas to be used by your API methods. These schemas can be described using JSON or YAML. See the Examples section at the bottom of this page for example models.  
*Type*: Map  
*Required*: No  
*CloudFormation compatibility*: This property is unique to AWS SAM and doesn't have an CloudFormation equivalent.

 `Name`   <a name="sam-api-name"></a>
A name for the API Gateway RestApi resource  
*Type*: String  
*Required*: No  
*CloudFormation compatibility*: This property is passed directly to the `[Name](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-name)` property of an `AWS::ApiGateway::RestApi` resource.

 `OpenApiVersion`   <a name="sam-api-openapiversion"></a>
Version of OpenApi to use. This can either be `2.0` for the Swagger specification, or one of the OpenApi 3.0 versions, like `3.0.1`. For more information about OpenAPI, see the [OpenAPI Specification](https://swagger.io/specification/).  
 AWS SAM creates a stage called `Stage` by default. Setting this property to any valid value will prevent the creation of the stage `Stage`. 
*Type*: String  
*Required*: No  
*CloudFormation compatibility*: This property is unique to AWS SAM and doesn't have an CloudFormation equivalent.

`PropagateTags`  <a name="sam-api-propagatetags"></a>
Indicate whether or not to pass tags from the `Tags` property to your [AWS::Serverless::Api](sam-specification-generated-resources-api.md) generated resources. Specify `True` to propagate tags in your generated resources.  
*Type*: Boolean  
*Required*: No  
*Default*: `False`  
*CloudFormation compatibility*: This property is unique to AWS SAM and doesn't have an CloudFormation equivalent.

`Policy`  <a name="sam-api-policy"></a>
A policy document that contains the permissions for the API. To set the ARN for the policy, use the `!Join` intrinsic function with `""` as delimiter and values of `"execute-api:/"` and `"*"`.  
*Type*: JSON  
*Required*: No  
*CloudFormation compatibility*: This property is passed directly to the [ Policy](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-policy) property of an `AWS::ApiGateway::RestApi` resource.

 `StageName`   <a name="sam-api-stagename"></a>
The name of the stage, which API Gateway uses as the first path segment in the invoke Uniform Resource Identifier (URI).  
To reference the stage resource, use `<api-logical-id>.Stage`. For more information about referencing resources generated when an [AWS::Serverless::Api](#sam-resource-api) resource is specified, see [CloudFormation resources generated when AWS::Serverless::Api is specified](sam-specification-generated-resources-api.md). For general information about generated CloudFormation resources, see [Generated CloudFormation resources for AWS SAM](sam-specification-generated-resources.md).  
*Type*: String  
*Required*: Yes  
*CloudFormation compatibility*: This property is similar to the `[StageName](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-stage.html#cfn-apigateway-stage-stagename)` property of an `AWS::ApiGateway::Stage` resource. It is required in SAM, but not required in API Gateway  
*Additional notes*: The Implicit API has a stage name of "Prod".

 `Tags`   <a name="sam-api-tags"></a>
A map (string to string) that specifies the tags to be added to this API Gateway stage. For details about valid keys and values for tags, see [Resource tag](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-resource-tags.html) in the *AWS CloudFormation User Guide*.  
*Type*: Map  
*Required*: No  
*CloudFormation compatibility*: This property is similar to the `[Tags](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-stage.html#cfn-apigateway-stage-tags)` property of an `AWS::ApiGateway::Stage` resource. The Tags property in SAM consists of Key:Value pairs; in CloudFormation it consists of a list of Tag objects.

 `TracingEnabled`   <a name="sam-api-tracingenabled"></a>
Indicates whether active tracing with X-Ray is enabled for the stage. For more information about X-Ray, see [Tracing user requests to REST APIs using X-Ray](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-xray.html) in the *API Gateway Developer Guide*.  
*Type*: Boolean  
*Required*: No  
*CloudFormation compatibility*: This property is passed directly to the `[TracingEnabled](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-stage.html#cfn-apigateway-stage-tracingenabled)` property of an `AWS::ApiGateway::Stage` resource.

 `Variables`   <a name="sam-api-variables"></a>
A map (string to string) that defines the stage variables, where the variable name is the key and the variable value is the value. Variable names are limited to alphanumeric characters. Values must match the following regular expression: `[A-Za-z0-9._~:/?#&=,-]+`.  
*Type*: Map  
*Required*: No  
*CloudFormation compatibility*: This property is passed directly to the `[Variables](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-stage.html#cfn-apigateway-stage-variables)` property of an `AWS::ApiGateway::Stage` resource.

## Return Values
<a name="sam-resource-api-return-values"></a>

### Ref
<a name="sam-resource-api-return-values-ref"></a>

When the logical ID of this resource is provided to the `Ref` intrinsic function, it returns the ID of the underlying API Gateway API.

For more information about using the `Ref` function, see [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference-ref.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference-ref.html) in the *AWS CloudFormation User Guide*. 

### Fn::GetAtt
<a name="sam-resource-api-return-values-fn--getatt"></a>

`Fn::GetAtt` 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 `Fn::GetAtt`, see [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference-getatt.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference-getatt.html) in the *AWS CloudFormation User Guide*. 

`RootResourceId`  <a name="RootResourceId-fn::getatt"></a>
The root resource ID for a `RestApi` resource, such as `a0bc123d4e`.

## Examples
<a name="sam-resource-api--examples"></a>

### SimpleApiExample
<a name="sam-resource-api--examples--simpleapiexample"></a>

A Hello World AWS SAM template file that contains a Lambda Function with an API endpoint. This is a full AWS SAM template file for a working serverless application.

#### YAML
<a name="sam-resource-api--examples--simpleapiexample--yaml"></a>

```
AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
Description: AWS SAM template with a simple API definition
Resources:
  ApiGatewayApi:
    Type: AWS::Serverless::Api
    Properties:
      StageName: prod
  ApiFunction: # Adds a GET method at the root resource via an Api event
    Type: AWS::Serverless::Function
    Properties:
      Events:
        ApiEvent:
          Type: Api
          Properties:
            Path: /
            Method: get
            RestApiId:
              Ref: ApiGatewayApi
      Runtime: python3.10
      Handler: index.handler
      InlineCode: |
        def handler(event, context):
            return {'body': 'Hello World!', 'statusCode': 200}
```

### ApiCorsExample
<a name="sam-resource-api--examples--apicorsexample"></a>

An AWS SAM template snippet with an API defined in an external Swagger file along with Lambda integrations and CORS configurations. This is just a portion of an AWS SAM template file showing an [AWS::Serverless::Api](#sam-resource-api) definition.

#### YAML
<a name="sam-resource-api--examples--apicorsexample--yaml"></a>

```
Resources:
  ApiGatewayApi:
    Type: AWS::Serverless::Api
    Properties:
      StageName: Prod
      # Allows www.example.com to call these APIs
      # SAM will automatically add AllowMethods with a list of methods for this API
      Cors: "'www.example.com'"
      DefinitionBody: # Pull in an OpenApi definition from S3
        'Fn::Transform':
          Name: 'AWS::Include'
          # Replace "bucket" with your bucket name
          Parameters:
            Location: s3://bucket/swagger.yaml
```

### ApiCognitoAuthExample
<a name="sam-resource-api--examples--apicognitoauthexample"></a>

An AWS SAM template snippet with an API that uses Amazon Cognito to authorize requests against the API. This is just a portion of an AWS SAM template file showing an [AWS::Serverless::Api](#sam-resource-api) definition.

#### YAML
<a name="sam-resource-api--examples--apicognitoauthexample--yaml"></a>

```
Resources:
  ApiGatewayApi:
    Type: AWS::Serverless::Api
    Properties:
      StageName: Prod
      Cors: "'*'"
      Auth:
        DefaultAuthorizer: MyCognitoAuthorizer
        Authorizers:
          MyCognitoAuthorizer:
            UserPoolArn:
              Fn::GetAtt: [MyCognitoUserPool, Arn]
```

### ApiModelsExample
<a name="sam-resource-api--examples--apimodelsexample"></a>

An AWS SAM template snippet with an API that includes a Models schema. This is just a portion of an AWS SAM template file, showing an [AWS::Serverless::Api](#sam-resource-api) definition with two model schemas.

#### YAML
<a name="sam-resource-api--examples--apimodelsexample--yaml"></a>

```
Resources:
  ApiGatewayApi:
    Type: AWS::Serverless::Api
    Properties:
      StageName: Prod
      Models:
        User:
          type: object
          required:
            - username
            - employee_id
          properties:
            username:
              type: string
            employee_id:
              type: integer
            department:
              type: string
        Item:
          type: object
          properties:
            count:
              type: integer
            category:
              type: string
            price:
              type: integer
```

### Caching example
<a name="sam-resource-api--examples--caching-example"></a>

A Hello World AWS SAM template file that contains a Lambda Function with an API endpoint. The API has caching enabled for one resource and method. For more information about caching, see [Enabling API caching to enhance responsiveness](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-caching.html) in the *API Gateway Developer Guide*.

#### YAML
<a name="sam-resource-api--examples--caching-example--yaml"></a>

```
AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
Description: AWS SAM template with a simple API definition with caching turned on
Resources:
  ApiGatewayApi:
    Type: AWS::Serverless::Api
    Properties:
      StageName: prod
      CacheClusterEnabled: true
      CacheClusterSize: '0.5'
      MethodSettings:
        - ResourcePath: /
          HttpMethod: GET
          CachingEnabled: true
          CacheTtlInSeconds: 300
      Tags:
        CacheMethods: All 

  ApiFunction: # Adds a GET method at the root resource via an Api event
    Type: AWS::Serverless::Function
    Properties:
      Events:
        ApiEvent:
          Type: Api
          Properties:
            Path: /
            Method: get
            RestApiId:
              Ref: ApiGatewayApi
      Runtime: python3.10
      Handler: index.handler
      InlineCode: |
        def handler(event, context):
            return {'body': 'Hello World!', 'statusCode': 200}
```

### Custom domain with a private API example
<a name="sam-resource-api--examples--custom-domain-example"></a>

A Hello World AWS SAM template file that contains a Lambda function with an API endpoint mapped to a private domain. The template creates a domain access association between a VPC endpoint and the private domain. For more information, see [Custom domain names for private APIs in API Gateway](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-private-custom-domains.html).

#### YAML
<a name="sam-resource-api--examples--custom-domain-example--yaml"></a>

```
AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
Description: AWS SAM template configured with a custom domain using a private API

Parameters:
    DomainName:
      Type: String
      Default: mydomain.example.com
    CertificateArn:
      Type: String
    HostedZoneId:
      Type: String
    VpcEndpointId:
      Type: String
    VpcEndpointDomainName:
      Type: String
    VpcEndpointHostedZoneId:
      Type: String

Resources:
  MyFunction:
    Type: AWS::Serverless::Function
    Properties:
      InlineCode: |
        def handler(event, context):
            return {'body': 'Hello World!', 'statusCode': 200}
      Handler: index.handler
      Runtime: python3.13
      Events:
        Fetch:
          Type: Api
          Properties:
            RestApiId:
              Ref: MyApi
            Method: Get
            Path: /get
  MyApi:
    Type: AWS::Serverless::Api
    Properties:
      StageName: Prod
      EndpointConfiguration:
        Type: PRIVATE
        VPCEndpointIds:
        - !Ref VpcEndpointId
      Policy:
        Version: '2012-10-17		 	 	 '
        Statement:
        - Effect: Allow
          Principal: '*'
          Action: execute-api:Invoke
          Resource: execute-api:/*
        - Effect: Deny
          Principal: '*'
          Action: execute-api:Invoke
          Resource: execute-api:/*
          Condition:
            StringNotEquals:
              aws:SourceVpce: !Ref VpcEndpointId
      Domain:
        DomainName: !Ref DomainName
        CertificateArn: !Ref CertificateArn
        EndpointConfiguration: PRIVATE
        BasePath:
        - /
        Route53:
          HostedZoneId: !Ref HostedZoneId
          VpcEndpointDomainName: !Ref VpcEndpointDomainName
          VpcEndpointHostedZoneId: !Ref VpcEndpointHostedZoneId
        AccessAssociation:
          VpcEndpointId: !Ref VpcEndpointId
        Policy:
          Version: '2012-10-17		 	 	 '
          Statement:
          - Effect: Allow
            Principal: '*'
            Action: execute-api:Invoke
            Resource: execute-api:/*
          - Effect: Deny
            Principal: '*'
            Action: execute-api:Invoke
            Resource: execute-api:/*
            Condition:
              StringNotEquals:
                aws:SourceVpce: !Ref VpcEndpointId
```

# ApiAuth
<a name="sam-property-api-apiauth"></a>

Configure authorization to control access to your API Gateway API.

For more information and examples for configuring access using AWS SAM see [Control API access with your AWS SAM template](serverless-controlling-access-to-apis.md).

## Syntax
<a name="sam-property-api-apiauth-syntax"></a>

To declare this entity in your AWS Serverless Application Model (AWS SAM) template, use the following syntax.

### YAML
<a name="sam-property-api-apiauth-syntax.yaml"></a>

```
  AddApiKeyRequiredToCorsPreflight: Boolean
  [AddDefaultAuthorizerToCorsPreflight](#sam-api-apiauth-adddefaultauthorizertocorspreflight): Boolean
  [ApiKeyRequired](#sam-api-apiauth-apikeyrequired): Boolean
  [Authorizers](#sam-api-apiauth-authorizers): CognitoAuthorizer | LambdaTokenAuthorizer | LambdaRequestAuthorizer | AWS_IAM
  [DefaultAuthorizer](#sam-api-apiauth-defaultauthorizer): String
  [InvokeRole](#sam-api-apiauth-invokerole): String
  [ResourcePolicy](#sam-api-apiauth-resourcepolicy): ResourcePolicyStatement
  [UsagePlan](#sam-api-apiauth-usageplan): ApiUsagePlan
```

**Note**  
The `Authorizers` property includes `AWS_IAM`, but there is no extra configuration needed for `AWS_IAM`. For an example, see [AWS IAM](#sam-property-api-apiauth--examples--aws_iam).

## Properties
<a name="sam-property-api-apiauth-properties"></a>

 `AddApiKeyRequiredToCorsPreflight`   <a name="sam-api-apiauth-addapikeyrequiredtocorspreflight"></a>
If the `ApiKeyRequired` and `Cors` properties are set, then setting `AddApiKeyRequiredToCorsPreflight` will cause the API key to be added to the `Options` property.  
*Type*: Boolean  
*Required*: No  
*Default*: `True`  
*CloudFormation compatibility*: This property is unique to AWS SAM and doesn't have an CloudFormation equivalent.

 `AddDefaultAuthorizerToCorsPreflight`   <a name="sam-api-apiauth-adddefaultauthorizertocorspreflight"></a>
If the `DefaultAuthorizer` and `Cors` properties are set, then setting `AddDefaultAuthorizerToCorsPreflight` will cause the default authorizer to be added to the `Options` property in the OpenAPI section.  
*Type*: Boolean  
*Required*: No  
*Default*: True  
*CloudFormation compatibility*: This property is unique to AWS SAM and doesn't have an CloudFormation equivalent.

 `ApiKeyRequired`   <a name="sam-api-apiauth-apikeyrequired"></a>
If set to true then an API key is required for all API events. For more information about API keys see [Create and Use Usage Plans with API Keys](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-api-usage-plans.html) in the *API Gateway Developer Guide*.  
*Type*: Boolean  
*Required*: No  
*CloudFormation compatibility*: This property is unique to AWS SAM and doesn't have an CloudFormation equivalent.

 `Authorizers`   <a name="sam-api-apiauth-authorizers"></a>
The authorizer used to control access to your API Gateway API.  
For more information, see [Control API access with your AWS SAM template](serverless-controlling-access-to-apis.md).  
*Type*: [CognitoAuthorizer](sam-property-api-cognitoauthorizer.md) \$1 [LambdaTokenAuthorizer](sam-property-api-lambdatokenauthorizer.md) \$1 [LambdaRequestAuthorizer](sam-property-api-lambdarequestauthorizer.md) \$1 AWS\$1IAM  
*Required*: No  
*Default*: None  
*CloudFormation compatibility*: This property is unique to AWS SAM and doesn't have an CloudFormation equivalent.  
*Additional notes*: SAM adds the Authorizers to the OpenApi definition of an Api.

 `DefaultAuthorizer`   <a name="sam-api-apiauth-defaultauthorizer"></a>
Specify a default authorizer for an API Gateway API, which will be used for authorizing API calls by default.  
If the Api EventSource for the function associated with this API is configured to use IAM Permissions, then this property must be set to `AWS_IAM`, otherwise an error will result.
*Type*: String  
*Required*: No  
*Default*: None  
*CloudFormation compatibility*: This property is unique to AWS SAM and doesn't have an CloudFormation equivalent.

 `InvokeRole`   <a name="sam-api-apiauth-invokerole"></a>
Sets integration credentials for all resources and methods to this value.  
`CALLER_CREDENTIALS` maps to `arn:aws:iam:::<user>/`, which uses the caller credentials to invoke the endpoint.  
*Valid values*: `CALLER_CREDENTIALS`, `NONE`, `IAMRoleArn`  
*Type*: String  
*Required*: No  
*Default*: `CALLER_CREDENTIALS`  
*CloudFormation compatibility*: This property is unique to AWS SAM and doesn't have an CloudFormation equivalent.

 `ResourcePolicy`   <a name="sam-api-apiauth-resourcepolicy"></a>
Configure Resource Policy for all methods and paths on an API.  
*Type*: [ResourcePolicyStatement](sam-property-api-resourcepolicystatement.md)  
*Required*: No  
*CloudFormation compatibility*: This property is unique to AWS SAM and doesn't have an CloudFormation equivalent.  
*Additional notes*: This setting can also be defined on individual `AWS::Serverless::Function` using the [ApiFunctionAuth](sam-property-function-apifunctionauth.md). This is required for APIs with `EndpointConfiguration: PRIVATE`.

 `UsagePlan`   <a name="sam-api-apiauth-usageplan"></a>
Configures a usage plan associated with this API. For more information about usage plans see [Create and Use Usage Plans with API Keys](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-api-usage-plans.html) in the *API Gateway Developer Guide*.  
This AWS SAM property generates three additional CloudFormation resources when this property is set: an [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-usageplan.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-usageplan.html), an [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-usageplankey.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-usageplankey.html), and an [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-apikey.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-apikey.html). For information about this scenario, see [UsagePlan property is specified](sam-specification-generated-resources-api.md#sam-specification-generated-resources-api-usage-plan). For general information about generated CloudFormation resources, see [Generated CloudFormation resources for AWS SAM](sam-specification-generated-resources.md).  
*Type*: [ApiUsagePlan](sam-property-api-apiusageplan.md)  
*Required*: No  
*CloudFormation compatibility*: This property is unique to AWS SAM and doesn't have an CloudFormation equivalent.

## Examples
<a name="sam-property-api-apiauth--examples"></a>

### CognitoAuth
<a name="sam-property-api-apiauth--examples--cognitoauth"></a>

Cognito Auth example

#### YAML
<a name="sam-property-api-apiauth--examples--cognitoauth--yaml"></a>

```
Auth:
  Authorizers:
    MyCognitoAuth:
     UserPoolArn:
       Fn::GetAtt:
         - MyUserPool
         - Arn
     AuthType: "COGNITO_USER_POOLS"
  DefaultAuthorizer: MyCognitoAuth
  InvokeRole: CALLER_CREDENTIALS
  AddDefaultAuthorizerToCorsPreflight: false
  ApiKeyRequired: false
  ResourcePolicy:
    CustomStatements: [{
      "Effect": "Allow",
      "Principal": "*",
      "Action": "execute-api:Invoke",
      "Resource": "execute-api:/Prod/GET/pets",
      "Condition": {
          "IpAddress": {
              "aws:SourceIp": "1.2.3.4"
          }
        }
    }]
    IpRangeDenylist:
      - "10.20.30.40"
```

### AWS IAM
<a name="sam-property-api-apiauth--examples--aws_iam"></a>

AWS IAM example

#### YAML
<a name="sam-property-api-apiauth--examples--cognitoauth--yaml"></a>

```
Auth:
  Authorizers: AWS_IAM
```

# ApiUsagePlan
<a name="sam-property-api-apiusageplan"></a>

Configures a usage plan for an API Gateway API. For more information about usage plans, see [Create and Use Usage Plans with API Keys](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-api-usage-plans.html) in the *API Gateway Developer Guide*.

## Syntax
<a name="sam-property-api-apiusageplan-syntax"></a>

To declare this entity in your AWS Serverless Application Model (AWS SAM) template, use the following syntax.

### YAML
<a name="sam-property-api-apiusageplan-syntax.yaml"></a>

```
  [CreateUsagePlan](#sam-api-apiusageplan-createusageplan): String
  [Description](#sam-api-apiusageplan-description): String
  [Quota](#sam-api-apiusageplan-quota): [QuotaSettings](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-usageplan.html#cfn-apigateway-usageplan-quota)
  [Tags](#sam-api-apiusageplan-tags): List
  [Throttle](#sam-api-apiusageplan-throttle): [ThrottleSettings](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-usageplan.html#cfn-apigateway-usageplan-throttle)
  [UsagePlanName](#sam-api-apiusageplan-usageplanname): String
```

## Properties
<a name="sam-property-api-apiusageplan-properties"></a>

 `CreateUsagePlan`   <a name="sam-api-apiusageplan-createusageplan"></a>
Determines how this usage plan is configured. Valid values are `PER_API`, `SHARED`, and `NONE`.  
`PER_API` creates [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-usageplan.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-usageplan.html), [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-apikey.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-apikey.html), and [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-usageplankey.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-usageplankey.html) resources that are specific to this API. These resources have logical IDs of `<api-logical-id>UsagePlan`, `<api-logical-id>ApiKey`, and `<api-logical-id>UsagePlanKey`, respectively.  
`SHARED` creates [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-usageplan.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-usageplan.html), [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-apikey.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-apikey.html), and [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-usageplankey.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-usageplankey.html) resources that are shared across any API that also has `CreateUsagePlan: SHARED` in the same AWS SAM template. These resources have logical IDs of `ServerlessUsagePlan`, `ServerlessApiKey`, and `ServerlessUsagePlanKey`, respectively. If you use this option, we recommend that you add additional configuration for this usage plan on only one API resource to avoid conflicting definitions and an uncertain state.  
`NONE` disables the creation or association of a usage plan with this API. This is only necessary if `SHARED` or `PER_API` is specified in the [Globals section of the AWS SAM template](sam-specification-template-anatomy-globals.md).  
*Valid values*: `PER_API`, `SHARED`, and `NONE`  
*Type*: String  
*Required*: Yes  
*CloudFormation compatibility*: This property is unique to AWS SAM and doesn't have an CloudFormation equivalent.

 `Description`   <a name="sam-api-apiusageplan-description"></a>
A description of the usage plan.  
*Type*: String  
*Required*: No  
*CloudFormation compatibility*: This property is passed directly to the `[Description](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-usageplan.html#cfn-apigateway-usageplan-description)` property of an `AWS::ApiGateway::UsagePlan` resource.

 `Quota`   <a name="sam-api-apiusageplan-quota"></a>
Configures the number of requests that users can make within a given interval.  
*Type*: [QuotaSettings](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-usageplan.html#cfn-apigateway-usageplan-quota)  
*Required*: No  
*CloudFormation compatibility*: This property is passed directly to the `[Quota](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-usageplan.html#cfn-apigateway-usageplan-quota)` property of an `AWS::ApiGateway::UsagePlan` resource.

 `Tags`   <a name="sam-api-apiusageplan-tags"></a>
An array of arbitrary tags (key-value pairs) to associate with the usage plan.  
This property uses the [CloudFormation Tag Type](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-resource-tags.html).  
*Type*: List  
*Required*: No  
*CloudFormation compatibility*: This property is passed directly to the `[Tags](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-usageplan.html#cfn-apigateway-usageplan-tags)` property of an `AWS::ApiGateway::UsagePlan` resource.

 `Throttle`   <a name="sam-api-apiusageplan-throttle"></a>
Configures the overall request rate (average requests per second) and burst capacity.  
*Type*: [ThrottleSettings](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-usageplan.html#cfn-apigateway-usageplan-throttle)  
*Required*: No  
*CloudFormation compatibility*: This property is passed directly to the `[Throttle](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-usageplan.html#cfn-apigateway-usageplan-throttle)` property of an `AWS::ApiGateway::UsagePlan` resource.

 `UsagePlanName`   <a name="sam-api-apiusageplan-usageplanname"></a>
A name for the usage plan.  
*Type*: String  
*Required*: No  
*CloudFormation compatibility*: This property is passed directly to the `[UsagePlanName](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-usageplan.html#cfn-apigateway-usageplan-usageplanname)` property of an `AWS::ApiGateway::UsagePlan` resource.

## Examples
<a name="sam-property-api-apiusageplan--examples"></a>

### UsagePlan
<a name="sam-property-api-apiusageplan--examples--usageplan"></a>

The following is a usage plan example.

#### YAML
<a name="sam-property-api-apiusageplan--examples--usageplan--yaml"></a>

```
Auth:
  UsagePlan:
    CreateUsagePlan: PER_API
    Description: Usage plan for this API
    Quota:
      Limit: 500
      Period: MONTH
    Throttle:
      BurstLimit: 100
      RateLimit: 50
    Tags:
      - Key: TagName
        Value: TagValue
```

# CognitoAuthorizer
<a name="sam-property-api-cognitoauthorizer"></a>

Define a Amazon Cognito User Pool authorizer.

For more information and examples, see [Control API access with your AWS SAM template](serverless-controlling-access-to-apis.md).

## Syntax
<a name="sam-property-api-cognitoauthorizer-syntax"></a>

To declare this entity in your AWS Serverless Application Model (AWS SAM) template, use the following syntax.

### YAML
<a name="sam-property-api-cognitoauthorizer-syntax.yaml"></a>

```
  [AuthorizationScopes](#sam-api-cognitoauthorizer-authorizationscopes): List
  [Identity](#sam-api-cognitoauthorizer-identity): CognitoAuthorizationIdentity
  [UserPoolArn](#sam-api-cognitoauthorizer-userpoolarn): String
```

## Properties
<a name="sam-property-api-cognitoauthorizer-properties"></a>

 `AuthorizationScopes`   <a name="sam-api-cognitoauthorizer-authorizationscopes"></a>
List of authorization scopes for this authorizer.  
*Type*: List  
*Required*: No  
*CloudFormation compatibility*: This property is unique to AWS SAM and doesn't have an CloudFormation equivalent.

 `Identity`   <a name="sam-api-cognitoauthorizer-identity"></a>
This property can be used to specify an `IdentitySource` in an incoming request for an authorizer.  
*Type*: [CognitoAuthorizationIdentity](sam-property-api-cognitoauthorizationidentity.md)  
*Required*: No  
*CloudFormation compatibility*: This property is unique to AWS SAM and doesn't have an CloudFormation equivalent.

 `UserPoolArn`   <a name="sam-api-cognitoauthorizer-userpoolarn"></a>
Can refer to a user pool/specify a userpool arn to which you want to add this cognito authorizer  
*Type*: String  
*Required*: Yes  
*CloudFormation compatibility*: This property is unique to AWS SAM and doesn't have an CloudFormation equivalent.

## Examples
<a name="sam-property-api-cognitoauthorizer--examples"></a>

### CognitoAuth
<a name="sam-property-api-cognitoauthorizer--examples--cognitoauth"></a>

Cognito Auth Example

#### YAML
<a name="sam-property-api-cognitoauthorizer--examples--cognitoauth--yaml"></a>

```
Auth:
  Authorizers:
    MyCognitoAuth:
      AuthorizationScopes:
        - scope1
        - scope2
      UserPoolArn:
        Fn::GetAtt:
          - MyCognitoUserPool
          - Arn
      Identity:
        Header: MyAuthorizationHeader
        ValidationExpression: myauthvalidationexpression
```

# CognitoAuthorizationIdentity
<a name="sam-property-api-cognitoauthorizationidentity"></a>

This property can be used to specify an IdentitySource in an incoming request for an authorizer. For more information about IdentitySource see the [ApiGateway Authorizer OpenApi extension](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-swagger-extensions-authorizer.html).

## Syntax
<a name="sam-property-api-cognitoauthorizationidentity-syntax"></a>

To declare this entity in your AWS Serverless Application Model (AWS SAM) template, use the following syntax.

### YAML
<a name="sam-property-api-cognitoauthorizationidentity-syntax.yaml"></a>

```
  [Header](#sam-api-cognitoauthorizationidentity-header): String
  [ReauthorizeEvery](#sam-api-cognitoauthorizationidentity-reauthorizeevery): Integer
  [ValidationExpression](#sam-api-cognitoauthorizationidentity-validationexpression): String
```

## Properties
<a name="sam-property-api-cognitoauthorizationidentity-properties"></a>

 `Header`   <a name="sam-api-cognitoauthorizationidentity-header"></a>
Specify the header name for Authorization in the OpenApi definition.  
*Type*: String  
*Required*: No  
*Default*: Authorization  
*CloudFormation compatibility*: This property is unique to AWS SAM and doesn't have an CloudFormation equivalent.

 `ReauthorizeEvery`   <a name="sam-api-cognitoauthorizationidentity-reauthorizeevery"></a>
The time-to-live (TTL) period, in seconds, that specifies how long API Gateway caches authorizer results. If you specify a value greater than 0, API Gateway caches the authorizer responses. By default, API Gateway sets this property to 300. The maximum value is 3600, or 1 hour.  
*Type*: Integer  
*Required*: No  
*Default*: 300  
*CloudFormation compatibility*: This property is unique to AWS SAM and doesn't have an CloudFormation equivalent.

 `ValidationExpression`   <a name="sam-api-cognitoauthorizationidentity-validationexpression"></a>
Specify a validation expression for validating the incoming Identity  
*Type*: String  
*Required*: No  
*CloudFormation compatibility*: This property is unique to AWS SAM and doesn't have an CloudFormation equivalent.

## Examples
<a name="sam-property-api-cognitoauthorizationidentity--examples"></a>

### CognitoAuthIdentity
<a name="sam-property-api-cognitoauthorizationidentity--examples--cognitoauthidentity"></a>

#### YAML
<a name="sam-property-api-cognitoauthorizationidentity--examples--cognitoauthidentity--yaml"></a>

```
Identity:
  Header: MyCustomAuthHeader
  ValidationExpression: Bearer.*
  ReauthorizeEvery: 30
```

# LambdaRequestAuthorizer
<a name="sam-property-api-lambdarequestauthorizer"></a>

Configure a Lambda Authorizer to control access to your API with a Lambda function.

For more information and examples, see [Control API access with your AWS SAM template](serverless-controlling-access-to-apis.md).

## Syntax
<a name="sam-property-api-lambdarequestauthorizer-syntax"></a>

To declare this entity in your AWS Serverless Application Model (AWS SAM) template, use the following syntax.

### YAML
<a name="sam-property-api-lambdarequestauthorizer-syntax.yaml"></a>

```
DisableFunctionDefaultPermissions: Boolean
[FunctionArn](#sam-api-lambdarequestauthorizer-functionarn): String
[FunctionInvokeRole](#sam-api-lambdarequestauthorizer-functioninvokerole): String
[FunctionPayloadType](#sam-api-lambdarequestauthorizer-functionpayloadtype): String
[Identity](#sam-api-lambdarequestauthorizer-identity): LambdaRequestAuthorizationIdentity
```

## Properties
<a name="sam-property-api-lambdarequestauthorizer-properties"></a>

 `DisableFunctionDefaultPermissions`   <a name="sam-api-lambdarequestauthorizer-disablefunctiondefaultpermissions"></a>
Specify `true` to prevent AWS SAM from automatically creating an `AWS::Lambda::Permissions` resource to provision permissions between your `AWS::Serverless::Api` resource and authorizer Lambda function.  
*Default value*: `false`  
*Type*: Boolean  
*Required*: No  
*CloudFormation compatibility*: This property is unique to AWS SAM and doesn't have an CloudFormation equivalent.

 `FunctionArn`   <a name="sam-api-lambdarequestauthorizer-functionarn"></a>
Specify the function ARN of the Lambda function which provides authorization for the API.  
AWS SAM will automatically create an `AWS::Lambda::Permissions` resource when `FunctionArn` is specified for `AWS::Serverless::Api`. The `AWS::Lambda::Permissions` resource provisions permissions between your API and authorizer Lambda function.
*Type*: String  
*Required*: Yes  
*CloudFormation compatibility*: This property is unique to AWS SAM and doesn't have an CloudFormation equivalent.

 `FunctionInvokeRole`   <a name="sam-api-lambdarequestauthorizer-functioninvokerole"></a>
Adds authorizer credentials to the OpenApi definition of the Lambda authorizer.  
*Type*: String  
*Required*: No  
*CloudFormation compatibility*: This property is unique to AWS SAM and doesn't have an CloudFormation equivalent.

 `FunctionPayloadType`   <a name="sam-api-lambdarequestauthorizer-functionpayloadtype"></a>
This property can be used to define the type of Lambda Authorizer for an API.  
*Valid values*: `TOKEN` or `REQUEST`  
*Type*: String  
*Required*: No  
*Default*: `TOKEN`  
*CloudFormation compatibility*: This property is unique to AWS SAM and doesn't have an CloudFormation equivalent.

 `Identity`   <a name="sam-api-lambdarequestauthorizer-identity"></a>
This property can be used to specify an `IdentitySource` in an incoming request for an authorizer. This property is only required if the `FunctionPayloadType` property is set to `REQUEST`.  
*Type*: [LambdaRequestAuthorizationIdentity](sam-property-api-lambdarequestauthorizationidentity.md)  
*Required*: Conditional  
*CloudFormation compatibility*: This property is unique to AWS SAM and doesn't have an CloudFormation equivalent.

## Examples
<a name="sam-property-api-lambdarequestauthorizer--examples"></a>

### LambdaRequestAuth
<a name="sam-property-api-lambdarequestauthorizer--examples--lambdarequestauth"></a>

#### YAML
<a name="sam-property-api-lambdarequestauthorizer--examples--lambdarequestauth--yaml"></a>

```
Authorizers:
  MyLambdaRequestAuth:
    FunctionPayloadType: REQUEST
    FunctionArn:
      Fn::GetAtt:
        - MyAuthFunction
        - Arn
    FunctionInvokeRole:
      Fn::GetAtt:
        - LambdaAuthInvokeRole
        - Arn
    Identity:
      Headers:
        - Authorization1
```

# LambdaRequestAuthorizationIdentity
<a name="sam-property-api-lambdarequestauthorizationidentity"></a>

This property can be used to specify an IdentitySource in an incoming request for an authorizer. For more information about IdentitySource see the [ApiGateway Authorizer OpenApi extension](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-swagger-extensions-authorizer.html).

## Syntax
<a name="sam-property-api-lambdarequestauthorizationidentity-syntax"></a>

To declare this entity in your AWS Serverless Application Model (AWS SAM) template, use the following syntax.

### YAML
<a name="sam-property-api-lambdarequestauthorizationidentity-syntax.yaml"></a>

```
  [Context](#sam-api-lambdarequestauthorizationidentity-context): List
  [Headers](#sam-api-lambdarequestauthorizationidentity-headers): List
  [QueryStrings](#sam-api-lambdarequestauthorizationidentity-querystrings): List
  [ReauthorizeEvery](#sam-api-lambdarequestauthorizationidentity-reauthorizeevery): Integer
  [StageVariables](#sam-api-lambdarequestauthorizationidentity-stagevariables): List
```

## Properties
<a name="sam-property-api-lambdarequestauthorizationidentity-properties"></a>

 `Context`   <a name="sam-api-lambdarequestauthorizationidentity-context"></a>
Converts the given context strings to the mapping expressions of format `context.contextString`.  
*Type*: List  
*Required*: No  
*CloudFormation compatibility*: This property is unique to AWS SAM and doesn't have an CloudFormation equivalent.

 `Headers`   <a name="sam-api-lambdarequestauthorizationidentity-headers"></a>
Converts the headers to comma-separated string of mapping expressions of format `method.request.header.name`.  
*Type*: List  
*Required*: No  
*CloudFormation compatibility*: This property is unique to AWS SAM and doesn't have an CloudFormation equivalent.

 `QueryStrings`   <a name="sam-api-lambdarequestauthorizationidentity-querystrings"></a>
Converts the given query strings to comma-separated string of mapping expressions of format `method.request.querystring.queryString`.  
*Type*: List  
*Required*: No  
*CloudFormation compatibility*: This property is unique to AWS SAM and doesn't have an CloudFormation equivalent.

 `ReauthorizeEvery`   <a name="sam-api-lambdarequestauthorizationidentity-reauthorizeevery"></a>
The time-to-live (TTL) period, in seconds, that specifies how long API Gateway caches authorizer results. If you specify a value greater than 0, API Gateway caches the authorizer responses. By default, API Gateway sets this property to 300. The maximum value is 3600, or 1 hour.  
*Type*: Integer  
*Required*: No  
*Default*: 300  
*CloudFormation compatibility*: This property is unique to AWS SAM and doesn't have an CloudFormation equivalent.

 `StageVariables`   <a name="sam-api-lambdarequestauthorizationidentity-stagevariables"></a>
Converts the given stage variables to comma-separated string of mapping expressions of format `stageVariables.stageVariable`.  
*Type*: List  
*Required*: No  
*CloudFormation compatibility*: This property is unique to AWS SAM and doesn't have an CloudFormation equivalent.

## Examples
<a name="sam-property-api-lambdarequestauthorizationidentity--examples"></a>

### LambdaRequestIdentity
<a name="sam-property-api-lambdarequestauthorizationidentity--examples--lambdarequestidentity"></a>

#### YAML
<a name="sam-property-api-lambdarequestauthorizationidentity--examples--lambdarequestidentity--yaml"></a>

```
Identity:
  QueryStrings:
    - auth
  Headers:
    - Authorization
  StageVariables:
    - VARIABLE
  Context:
    - authcontext
  ReauthorizeEvery: 100
```

# LambdaTokenAuthorizer
<a name="sam-property-api-lambdatokenauthorizer"></a>

Configure a Lambda Authorizer to control access to your API with a Lambda function.

For more information and examples, see [Control API access with your AWS SAM template](serverless-controlling-access-to-apis.md).

## Syntax
<a name="sam-property-api-lambdatokenauthorizer-syntax"></a>

To declare this entity in your AWS Serverless Application Model (AWS SAM) template, use the following syntax.

### YAML
<a name="sam-property-api-lambdatokenauthorizer-syntax.yaml"></a>

```
DisableFunctionDefaultPermissions: Boolean
[FunctionArn](#sam-api-lambdatokenauthorizer-functionarn): String
[FunctionInvokeRole](#sam-api-lambdatokenauthorizer-functioninvokerole): String
[FunctionPayloadType](#sam-api-lambdatokenauthorizer-functionpayloadtype): String
[Identity](#sam-api-lambdatokenauthorizer-identity): LambdaTokenAuthorizationIdentity
```

## Properties
<a name="sam-property-api-lambdatokenauthorizer-properties"></a>

 `DisableFunctionDefaultPermissions`   <a name="sam-api-lambdatokenauthorizer-disablefunctiondefaultpermissions"></a>
Specify `true` to prevent AWS SAM from automatically creating an `AWS::Lambda::Permissions` resource to provision permissions between your `AWS::Serverless::Api` resource and authorizer Lambda function.  
*Default value*: `false`  
*Type*: Boolean  
*Required*: No  
*CloudFormation compatibility*: This property is unique to AWS SAM and doesn't have an CloudFormation equivalent.

 `FunctionArn`   <a name="sam-api-lambdatokenauthorizer-functionarn"></a>
Specify the function ARN of the Lambda function which provides authorization for the API.  
AWS SAM will automatically create an `AWS::Lambda::Permissions` resource when `FunctionArn` is specified for `AWS::Serverless::Api`. The `AWS::Lambda::Permissions` resource provisions permissions between your API and authorizer Lambda function.
*Type*: String  
*Required*: Yes  
*CloudFormation compatibility*: This property is unique to AWS SAM and doesn't have an CloudFormation equivalent.

 `FunctionInvokeRole`   <a name="sam-api-lambdatokenauthorizer-functioninvokerole"></a>
Adds authorizer credentials to the OpenApi definition of the Lambda authorizer.  
*Type*: String  
*Required*: No  
*CloudFormation compatibility*: This property is unique to AWS SAM and doesn't have an CloudFormation equivalent.

 `FunctionPayloadType`   <a name="sam-api-lambdatokenauthorizer-functionpayloadtype"></a>
This property can be used to define the type of Lambda Authorizer for an Api.  
*Valid values*: `TOKEN` or `REQUEST`  
*Type*: String  
*Required*: No  
*Default*: `TOKEN`  
*CloudFormation compatibility*: This property is unique to AWS SAM and doesn't have an CloudFormation equivalent.

 `Identity`   <a name="sam-api-lambdatokenauthorizer-identity"></a>
This property can be used to specify an `IdentitySource` in an incoming request for an authorizer. This property is only required if the `FunctionPayloadType` property is set to `REQUEST`.  
*Type*: [LambdaTokenAuthorizationIdentity](sam-property-api-lambdatokenauthorizationidentity.md)  
*Required*: Conditional  
*CloudFormation compatibility*: This property is unique to AWS SAM and doesn't have an CloudFormation equivalent.

## Examples
<a name="sam-property-api-lambdatokenauthorizer--examples"></a>

### LambdaTokenAuth
<a name="sam-property-api-lambdatokenauthorizer--examples--lambdatokenauth"></a>

#### YAML
<a name="sam-property-api-lambdatokenauthorizer--examples--lambdatokenauth--yaml"></a>

```
Authorizers:
  MyLambdaTokenAuth:
    FunctionArn:
      Fn::GetAtt:
        - MyAuthFunction
        - Arn
    Identity:
      Header: MyCustomAuthHeader # OPTIONAL; Default: 'Authorization'
      ValidationExpression: mycustomauthexpression # OPTIONAL
      ReauthorizeEvery: 20 # OPTIONAL; Service Default: 300
```

### BasicLambdaTokenAuth
<a name="sam-property-api-lambdatokenauthorizer--examples--basiclambdatokenauth"></a>

#### YAML
<a name="sam-property-api-lambdatokenauthorizer--examples--basiclambdatokenauth--yaml"></a>

```
Authorizers:
  MyLambdaTokenAuth:
    FunctionArn:
      Fn::GetAtt:
        - MyAuthFunction
        - Arn
```

# LambdaTokenAuthorizationIdentity
<a name="sam-property-api-lambdatokenauthorizationidentity"></a>

This property can be used to specify an IdentitySource in an incoming request for an authorizer. For more information about IdentitySource see the [ApiGateway Authorizer OpenApi extension](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-swagger-extensions-authorizer.html).

## Syntax
<a name="sam-property-api-lambdatokenauthorizationidentity-syntax"></a>

 To declare this entity in your AWS Serverless Application Model (AWS SAM) template, use the following syntax. 

### YAML
<a name="sam-property-api-lambdatokenauthorizationidentity-syntax.yaml"></a>

```
  [Header](#sam-api-lambdatokenauthorizationidentity-header): String
  [ReauthorizeEvery](#sam-api-lambdatokenauthorizationidentity-reauthorizeevery): Integer
  [ValidationExpression](#sam-api-lambdatokenauthorizationidentity-validationexpression): String
```

## Properties
<a name="sam-property-api-lambdatokenauthorizationidentity-properties"></a>

 `Header`   <a name="sam-api-lambdatokenauthorizationidentity-header"></a>
Specify the header name for Authorization in the OpenApi definition.  
*Type*: String  
*Required*: No  
*Default*: Authorization  
*CloudFormation compatibility*: This property is unique to AWS SAM and doesn't have an CloudFormation equivalent.

 `ReauthorizeEvery`   <a name="sam-api-lambdatokenauthorizationidentity-reauthorizeevery"></a>
The time-to-live (TTL) period, in seconds, that specifies how long API Gateway caches authorizer results. If you specify a value greater than 0, API Gateway caches the authorizer responses. By default, API Gateway sets this property to 300. The maximum value is 3600, or 1 hour.  
*Type*: Integer  
*Required*: No  
*Default*: 300  
*CloudFormation compatibility*: This property is unique to AWS SAM and doesn't have an CloudFormation equivalent.

 `ValidationExpression`   <a name="sam-api-lambdatokenauthorizationidentity-validationexpression"></a>
Specify a validation expression for validating the incoming Identity.  
*Type*: String  
*Required*: No  
*CloudFormation compatibility*: This property is unique to AWS SAM and doesn't have an CloudFormation equivalent.

## Examples
<a name="sam-property-api-lambdatokenauthorizationidentity--examples"></a>

### LambdaTokenIdentity
<a name="sam-property-api-lambdatokenauthorizationidentity--examples--lambdatokenidentity"></a>

#### YAML
<a name="sam-property-api-lambdatokenauthorizationidentity--examples--lambdatokenidentity--yaml"></a>

```
Identity:
  Header: MyCustomAuthHeader
  ValidationExpression: Bearer.*
  ReauthorizeEvery: 30
```

# ResourcePolicyStatement
<a name="sam-property-api-resourcepolicystatement"></a>

Configures a resource policy for all methods and paths of an API. For more information about resource policies, see [Controlling access to an API with API Gateway resource policies](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-resource-policies.html) in the *API Gateway Developer Guide*.

## Syntax
<a name="sam-property-api-resourcepolicystatement-syntax"></a>

To declare this entity in your AWS Serverless Application Model (AWS SAM) template, use the following syntax.

### YAML
<a name="sam-property-api-resourcepolicystatement-syntax.yaml"></a>

```
  [AwsAccountBlacklist](#sam-api-resourcepolicystatement-awsaccountblacklist): List
  [AwsAccountWhitelist](#sam-api-resourcepolicystatement-awsaccountwhitelist): List
  [CustomStatements](#sam-api-resourcepolicystatement-customstatements): List
  [IntrinsicVpcBlacklist](#sam-api-resourcepolicystatement-intrinsicvpcblacklist): List
  [IntrinsicVpcWhitelist](#sam-api-resourcepolicystatement-intrinsicvpcwhitelist): List
  [IntrinsicVpceBlacklist](#sam-api-resourcepolicystatement-intrinsicvpceblacklist): List
  [IntrinsicVpceWhitelist](#sam-api-resourcepolicystatement-intrinsicvpcewhitelist): List
  [IpRangeBlacklist](#sam-api-resourcepolicystatement-iprangeblacklist): List
  [IpRangeWhitelist](#sam-api-resourcepolicystatement-iprangewhitelist): List
  [SourceVpcBlacklist](#sam-api-resourcepolicystatement-sourcevpcblacklist): List
  [SourceVpcWhitelist](#sam-api-resourcepolicystatement-sourcevpcwhitelist): List
```

## Properties
<a name="sam-property-api-resourcepolicystatement-properties"></a>

 `AwsAccountBlacklist`   <a name="sam-api-resourcepolicystatement-awsaccountblacklist"></a>
The AWS accounts to block.  
*Type*: List of String  
*Required*: No  
*CloudFormation compatibility*: This property is unique to AWS SAM and doesn't have an CloudFormation equivalent.

 `AwsAccountWhitelist`   <a name="sam-api-resourcepolicystatement-awsaccountwhitelist"></a>
The AWS accounts to allow. For an example use of this property, see the Examples section at the bottom of this page.  
*Type*: List of String  
*Required*: No  
*CloudFormation compatibility*: This property is unique to AWS SAM and doesn't have an CloudFormation equivalent.

 `CustomStatements`   <a name="sam-api-resourcepolicystatement-customstatements"></a>
A list of custom resource policy statements to apply to this API. For an example use of this property, see the Examples section at the bottom of this page.  
*Type*: List  
*Required*: No  
*CloudFormation compatibility*: This property is unique to AWS SAM and doesn't have an CloudFormation equivalent.

 `IntrinsicVpcBlacklist`   <a name="sam-api-resourcepolicystatement-intrinsicvpcblacklist"></a>
The list of virtual private clouds (VPCs) to block, where each VPC is specified as a reference such as a [dynamic reference](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/dynamic-references.html) or the `Ref` [intrinsic function](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference-ref.html). For an example use of this property, see the Examples section at the bottom of this page.  
*Type*: List  
*Required*: No  
*CloudFormation compatibility*: This property is unique to AWS SAM and doesn't have an CloudFormation equivalent.

 `IntrinsicVpcWhitelist`   <a name="sam-api-resourcepolicystatement-intrinsicvpcwhitelist"></a>
The list of VPCs to allow, where each VPC is specified as a reference such as a [dynamic reference](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/dynamic-references.html) or the `Ref` [intrinsic function](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference-ref.html).  
*Type*: List  
*Required*: No  
*CloudFormation compatibility*: This property is unique to AWS SAM and doesn't have an CloudFormation equivalent.

 `IntrinsicVpceBlacklist`   <a name="sam-api-resourcepolicystatement-intrinsicvpceblacklist"></a>
The list of VPC endpoints to block, where each VPC endpoint is specified as a reference such as a [dynamic reference](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/dynamic-references.html) or the `Ref` [intrinsic function](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference-ref.html).  
*Type*: List  
*Required*: No  
*CloudFormation compatibility*: This property is unique to AWS SAM and doesn't have an CloudFormation equivalent.

 `IntrinsicVpceWhitelist`   <a name="sam-api-resourcepolicystatement-intrinsicvpcewhitelist"></a>
The list of VPC endpoints to allow, where each VPC endpoint is specified as a reference such as a [dynamic reference](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/dynamic-references.html) or the `Ref` [intrinsic function](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference-ref.html). For an example use of this property, see the Examples section at the bottom of this page.  
*Type*: List  
*Required*: No  
*CloudFormation compatibility*: This property is unique to AWS SAM and doesn't have an CloudFormation equivalent.

 `IpRangeBlacklist`   <a name="sam-api-resourcepolicystatement-iprangeblacklist"></a>
The IP addresses or address ranges to block. For an example use of this property, see the Examples section at the bottom of this page.  
*Type*: List  
*Required*: No  
*CloudFormation compatibility*: This property is unique to AWS SAM and doesn't have an CloudFormation equivalent.

 `IpRangeWhitelist`   <a name="sam-api-resourcepolicystatement-iprangewhitelist"></a>
The IP addresses or address ranges to allow.  
*Type*: List  
*Required*: No  
*CloudFormation compatibility*: This property is unique to AWS SAM and doesn't have an CloudFormation equivalent.

 `SourceVpcBlacklist`   <a name="sam-api-resourcepolicystatement-sourcevpcblacklist"></a>
The source VPC or VPC endpoints to block. Source VPC names must start with `"vpc-"` and source VPC endpoint names must start with `"vpce-"`. For an example use of this property, see the Examples section at the bottom of this page.  
*Type*: List  
*Required*: No  
*CloudFormation compatibility*: This property is unique to AWS SAM and doesn't have an CloudFormation equivalent.

 `SourceVpcWhitelist`   <a name="sam-api-resourcepolicystatement-sourcevpcwhitelist"></a>
The source VPC or VPC endpoints to allow. Source VPC names must start with `"vpc-"` and source VPC endpoint names must start with `"vpce-"`.  
*Type*: List  
*Required*: No  
*CloudFormation compatibility*: This property is unique to AWS SAM and doesn't have an CloudFormation equivalent.

## Examples
<a name="sam-property-api-resourcepolicystatement--examples"></a>

### Resource Policy Example
<a name="sam-property-api-resourcepolicystatement--examples--resource-policy-example"></a>

The following example blocks two IP addresses and a source VPC, and allows an AWS account.

#### YAML
<a name="sam-property-api-resourcepolicystatement--examples--resource-policy-example--yaml"></a>

```
Auth:
  ResourcePolicy:
    CustomStatements: [{
                         "Effect": "Allow",
                         "Principal": "*",
                         "Action": "execute-api:Invoke",
                         "Resource": "execute-api:/Prod/GET/pets",
                         "Condition": {
                           "IpAddress": {
                             "aws:SourceIp": "1.2.3.4"
                           }
                         }
                       }]
    IpRangeBlacklist:
      - "10.20.30.40"
      - "1.2.3.4"
    SourceVpcBlacklist:
      - "vpce-1a2b3c4d"
    AwsAccountWhitelist:
      - "111122223333"
    IntrinsicVpcBlacklist:
      - "{{resolve:ssm:SomeVPCReference:1}}" 
      - !Ref MyVPC
    IntrinsicVpceWhitelist:
      - "{{resolve:ssm:SomeVPCEReference:1}}" 
      - !Ref MyVPCE
```

# ApiDefinition
<a name="sam-property-api-apidefinition"></a>

An OpenAPI document defining the API.

## Syntax
<a name="sam-property-api-apidefinition-syntax"></a>

To declare this entity in your AWS Serverless Application Model (AWS SAM) template, use the following syntax.

### YAML
<a name="sam-property-api-apidefinition-syntax.yaml"></a>

```
  [Bucket](#sam-api-apidefinition-bucket): String
  [Key](#sam-api-apidefinition-key): String
  [Version](#sam-api-apidefinition-version): String
```

## Properties
<a name="sam-property-api-apidefinition-properties"></a>

 `Bucket`   <a name="sam-api-apidefinition-bucket"></a>
The name of the Amazon S3 bucket where the OpenAPI file is stored.  
*Type*: String  
*Required*: Yes  
*CloudFormation compatibility*: This property is passed directly to the `[Bucket](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-apigateway-restapi-s3location.html#cfn-apigateway-restapi-s3location-bucket)` property of the `AWS::ApiGateway::RestApi` `S3Location` data type.

 `Key`   <a name="sam-api-apidefinition-key"></a>
The Amazon S3 key of the OpenAPI file.  
*Type*: String  
*Required*: Yes  
*CloudFormation compatibility*: This property is passed directly to the `[Key](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-apigateway-restapi-s3location.html#cfn-apigateway-restapi-s3location-key)` property of the `AWS::ApiGateway::RestApi` `S3Location` data type.

 `Version`   <a name="sam-api-apidefinition-version"></a>
For versioned objects, the version of the OpenAPI file.  
*Type*: String  
*Required*: No  
*CloudFormation compatibility*: This property is passed directly to the `[Version](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-apigateway-restapi-s3location.html#cfn-apigateway-restapi-s3location-version)` property of the `AWS::ApiGateway::RestApi` `S3Location` data type.

## Examples
<a name="sam-property-api-apidefinition--examples"></a>

### Definition Uri example
<a name="sam-property-api-apidefinition--examples--definition-uri-example"></a>

API Definition example

#### YAML
<a name="sam-property-api-apidefinition--examples--definition-uri-example--yaml"></a>

```
DefinitionUri:
  Bucket: amzn-s3-demo-bucket-name
  Key: mykey-name
  Version: 121212
```

# CorsConfiguration
<a name="sam-property-api-corsconfiguration"></a>

Manage cross-origin resource sharing (CORS) for your API Gateway APIs. Specify the domain to allow as a string or specify a dictionary with additional Cors configuration.

**Note**  
CORS requires AWS SAM to modify your OpenAPI definition. Create an inline OpenAPI definition in the `DefinitionBody` to turn on CORS. If the `CorsConfiguration` is set in the OpenAPI definition and also at the property level, AWS SAM merges them. The property level takes precedence over the OpenAPI definition.

For more information about CORS, see [Enable CORS for an API Gateway REST API Resource](https://docs.aws.amazon.com/apigateway/latest/developerguide/how-to-cors.html) in the *API Gateway Developer Guide*.

## Syntax
<a name="sam-property-api-corsconfiguration-syntax"></a>

To declare this entity in your AWS Serverless Application Model (AWS SAM) template, use the following syntax.

### YAML
<a name="sam-property-api-corsconfiguration-syntax.yaml"></a>

```
  [AllowCredentials](#sam-api-corsconfiguration-allowcredentials): Boolean
  [AllowHeaders](#sam-api-corsconfiguration-allowheaders): String
  [AllowMethods](#sam-api-corsconfiguration-allowmethods): String
  [AllowOrigin](#sam-api-corsconfiguration-alloworigin): String
  [MaxAge](#sam-api-corsconfiguration-maxage): String
```

## Properties
<a name="sam-property-api-corsconfiguration-properties"></a>

 `AllowCredentials`   <a name="sam-api-corsconfiguration-allowcredentials"></a>
Boolean indicating whether request is allowed to contain credentials.  
*Type*: Boolean  
*Required*: No  
*CloudFormation compatibility*: This property is unique to AWS SAM and doesn't have an CloudFormation equivalent.

 `AllowHeaders`   <a name="sam-api-corsconfiguration-allowheaders"></a>
String of headers to allow.  
*Type*: String  
*Required*: No  
*CloudFormation compatibility*: This property is unique to AWS SAM and doesn't have an CloudFormation equivalent.

 `AllowMethods`   <a name="sam-api-corsconfiguration-allowmethods"></a>
String containing the HTTP methods to allow.  
*Type*: String  
*Required*: No  
*CloudFormation compatibility*: This property is unique to AWS SAM and doesn't have an CloudFormation equivalent.

 `AllowOrigin`   <a name="sam-api-corsconfiguration-alloworigin"></a>
String of origin to allow. This can be a comma-separated list in string format.  
*Type*: String  
*Required*: Yes  
*CloudFormation compatibility*: This property is unique to AWS SAM and doesn't have an CloudFormation equivalent.

 `MaxAge`   <a name="sam-api-corsconfiguration-maxage"></a>
String containing the number of seconds to cache CORS Preflight request.  
*Type*: String  
*Required*: No  
*CloudFormation compatibility*: This property is unique to AWS SAM and doesn't have an CloudFormation equivalent.

## Examples
<a name="sam-property-api-corsconfiguration--examples"></a>

### CorsConfiguration
<a name="sam-property-api-corsconfiguration--examples--corsconfiguration"></a>

CORS Configuration example. This is just a portion of an AWS SAM template file showing an [AWS::Serverless::Api](sam-resource-api.md) definition with CORS configured and a [AWS::Serverless::Function](sam-resource-function.md). If you use a Lambda proxy integration or a HTTP proxy integration, your backend must return the `Access-Control-Allow-Origin`, `Access-Control-Allow-Methods`, and `Access-Control-Allow-Headers` headers.

#### YAML
<a name="sam-property-api-corsconfiguration--examples--corsconfiguration--yaml"></a>

```
Resources:
  ApiGatewayApi:
    Type: AWS::Serverless::Api
    Properties:
      StageName: Prod
      Cors:
        AllowMethods: "'POST, GET'"
        AllowHeaders: "'X-Forwarded-For'"
        AllowOrigin: "'https://example.com'"
        MaxAge: "'600'"
        AllowCredentials: true
  ApiFunction: # Adds a GET method at the root resource via an Api event
    Type: AWS::Serverless::Function
    Properties:
      Events:
        ApiEvent:
          Type: Api
          Properties:
            Path: /
            Method: get
            RestApiId:
              Ref: ApiGatewayApi
      Runtime: python3.10
      Handler: index.handler
      InlineCode: |
        import json
        def handler(event, context):
          return {
          'statusCode': 200,
          'headers': {
            'Access-Control-Allow-Headers': 'Content-Type',
            'Access-Control-Allow-Origin': 'https://example.com',
            'Access-Control-Allow-Methods': 'POST, GET'
            },
          'body': json.dumps('Hello from Lambda!')
          }
```

# DomainConfiguration
<a name="sam-property-api-domainconfiguration"></a>

Configures a custom domain for an API.

## Syntax
<a name="sam-property-api-domainconfiguration-syntax"></a>

To declare this entity in your AWS Serverless Application Model (AWS SAM) template, use the following syntax.

### YAML
<a name="sam-property-api-domainconfiguration-syntax.yaml"></a>

```
  [AccessAssociation](#sam-api-domainconfiguration-domainaccessassociation): DomainAccessAssociation
  [BasePath](#sam-api-domainconfiguration-basepath): List
  [CertificateArn](#sam-api-domainconfiguration-certificatearn): String
  [DomainName](#sam-api-domainconfiguration-domainname): String
  [EndpointConfiguration](#sam-api-domainconfiguration-endpointconfiguration): String
  [MutualTlsAuthentication](#sam-api-domainconfiguration-mutualtlsauthentication): [MutualTlsAuthentication](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-domainname.html#cfn-apigateway-domainname-mutualtlsauthentication)
  [NormalizeBasePath](#sam-api-domainconfiguration-normalizebasepath): Boolean
  [OwnershipVerificationCertificateArn](#sam-api-domainconfiguration-ownershipverificationcertificatearn): String
  [Policy: ](#sam-api-domainconfiguration-policy)Json
  [Route53](#sam-api-domainconfiguration-route53): Route53Configuration
  [SecurityPolicy](#sam-api-domainconfiguration-securitypolicy): String
```

## Properties
<a name="sam-property-api-domainconfiguration-properties"></a>

 `AccessAssociation`   <a name="sam-api-domainconfiguration-domainaccessassociation"></a>
The configuration required to generate ` AWS::ApiGateway::DomainNameAccessAssociation` resource.  
AWS SAM generates an [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-domainnameaccessassociation.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-domainnameaccessassociation.html) resource when this property is set. For information about generated CloudFormation resources, see [Generated CloudFormation resources for AWS SAM](sam-specification-generated-resources.md).  
*Type*: [DomainAccessAssociation](sam-property-api-domainaccessassociation.md)  
*Required*: No  
*CloudFormation compatibility*: This property is unique to AWS SAM and doesn't have an CloudFormation equivalent.

 `BasePath`   <a name="sam-api-domainconfiguration-basepath"></a>
A list of the basepaths to configure with the Amazon API Gateway domain name.  
*Type*: List  
*Required*: No  
*Default*: /  
*CloudFormation compatibility*: This property is similar to the `[BasePath](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-basepathmapping.html#cfn-apigateway-basepathmapping-basepath)` property of an `AWS::ApiGateway::BasePathMapping` resource. AWS SAM creates multiple `AWS::ApiGateway::BasePathMapping` resources, one per `BasePath` specified in this property.

 `CertificateArn`   <a name="sam-api-domainconfiguration-certificatearn"></a>
The Amazon Resource Name (ARN) of an AWS managed certificate this domain name's endpoint. AWS Certificate Manager is the only supported source.  
*Type*: String  
*Required*: Yes  
*CloudFormation compatibility*: This property is similar to the `[CertificateArn](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-domainname.html#cfn-apigateway-domainname-certificatearn)` property of an `AWS::ApiGateway::DomainName` resource. If `EndpointConfiguration` is set to `REGIONAL` (the default value), `CertificateArn` maps to [RegionalCertificateArn](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-domainname.html#cfn-apigateway-domainname-regionalcertificatearn) in `AWS::ApiGateway::DomainName`. If the `EndpointConfiguration` is set to `EDGE`, `CertificateArn` maps to [CertificateArn](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-domainname.html#cfn-apigateway-domainname-certificatearn) in `AWS::ApiGateway::DomainName`. If `EndpointConfiguration` is set to `PRIVATE`, this property is passed to the [AWS::ApiGateway::DomainNameV2](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-domainnamev2) resource.  
*Additional notes*: For an `EDGE` endpoint, you must create the certificate in the `us-east-1` AWS Region.

 `DomainName`   <a name="sam-api-domainconfiguration-domainname"></a>
The custom domain name for your API Gateway API. Uppercase letters are not supported.  
AWS SAM generates an [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-domainname.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-domainname.html) resource when this property is set. For information about this scenario, see [DomainName property is specified](sam-specification-generated-resources-api.md#sam-specification-generated-resources-api-domain-name). For information about generated CloudFormation resources, see [Generated CloudFormation resources for AWS SAM](sam-specification-generated-resources.md).  
*Type*: String  
*Required*: Yes  
*CloudFormation compatibility*: This property is passed directly to the `[DomainName](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-domainname.html#cfn-apigateway-domainname-domainname)` property of an `AWS::ApiGateway::DomainName` resource, or to [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-domainnamev2](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-domainnamev2) when EndpointConfiguration is set to `PRIVATE`.

 `EndpointConfiguration`   <a name="sam-api-domainconfiguration-endpointconfiguration"></a>
Defines the type of API Gateway endpoint to map to the custom domain. The value of this property determines how the `CertificateArn` property is mapped in CloudFormation.  
*Valid values*: `EDGE`, `REGIONAL`, or `PRIVATE`  
*Type*: String  
*Required*: No  
*Default*: `REGIONAL`  
*CloudFormation compatibility*: This property is unique to AWS SAM and doesn't have an CloudFormation equivalent.

 `MutualTlsAuthentication`   <a name="sam-api-domainconfiguration-mutualtlsauthentication"></a>
The mutual Transport Layer Security (TLS) authentication configuration for a custom domain name.  
*Type*: [MutualTlsAuthentication](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-domainname.html#cfn-apigateway-domainname-mutualtlsauthentication)  
*Required*: No  
*CloudFormation compatibility*: This property is passed directly to the `[MutualTlsAuthentication](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-domainname.html#cfn-apigateway-domainname-mutualtlsauthentication)` property of an `AWS::ApiGateway::DomainName` resource.

 `NormalizeBasePath`   <a name="sam-api-domainconfiguration-normalizebasepath"></a>
Indicates whether non-alphanumeric characters are allowed in basepaths defined by the `BasePath` property. When set to `True`, non-alphanumeric characters are removed from basepaths.  
Use `NormalizeBasePath` with the `BasePath` property.  
*Type*: Boolean  
*Required*: No  
*Default*: True  
*CloudFormation compatibility*: This property is unique to AWS SAM and doesn't have an CloudFormation equivalent.

 `OwnershipVerificationCertificateArn`   <a name="sam-api-domainconfiguration-ownershipverificationcertificatearn"></a>
The ARN of the public certificate issued by ACM to validate ownership of your custom domain. Required only when you configure mutual TLS and you specify an ACM imported or private CA certificate ARN for the `CertificateArn`.  
*Type*: String  
*Required*: No  
*CloudFormation compatibility*: This property is passed directly to the `[OwnershipVerificationCertificateArn](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-domainname.html#cfn-apigateway-domainname-ownershipverificationcertificatearn)` property of an `AWS::ApiGateway::DomainName` resource.

 `Policy`   <a name="sam-api-domainconfiguration-policy"></a>
The IAM policy to attach to the API Gateway domain name. Only applicable when `EndpointConfiguration` is set to `PRIVATE`.  
*Type*: Json  
*Required*: No  
*CloudFormation compatibility*: This property is passed directly to the `Policy` property of an `AWS::ApiGateway::DomainNameV2` resource when `EndpointConfiguration` is set to `PRIVATE`. For examples of valid policy documents, see [AWS::ApiGateway::DomainNameV2](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-domainnamev2).

 `Route53`   <a name="sam-api-domainconfiguration-route53"></a>
Defines an Amazon Route 53 configuration.  
*Type*: [Route53Configuration](sam-property-api-route53configuration.md)  
*Required*: No  
*CloudFormation compatibility*: This property is unique to AWS SAM and doesn't have an CloudFormation equivalent.

 `SecurityPolicy`   <a name="sam-api-domainconfiguration-securitypolicy"></a>
The TLS version plus cipher suite for this domain name.  
*Type*: String  
*Required*: No  
*CloudFormation compatibility*: This property is passed directly to the `[SecurityPolicy](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-domainname.html#cfn-apigateway-domainname-securitypolicy)` property of an `AWS::ApiGateway::DomainName` resource, or to [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-domainnamev2](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-domainnamev2) when `EndpointConfiguration` is set to `PRIVATE`. For `PRIVATE` endpoints, only TLS\$11\$12 is supported.

## Examples
<a name="sam-property-api-domainconfiguration--examples"></a>

### DomainName
<a name="sam-property-api-domainconfiguration--examples--domainname"></a>

DomainName example

#### YAML
<a name="sam-property-api-domainconfiguration--examples--domainname--yaml"></a>

```
Domain:
  DomainName: www.example.com
  CertificateArn: arn-example
  EndpointConfiguration: EDGE
  Route53:
    HostedZoneId: Z1PA6795UKMFR9
  BasePath:
    - foo
    - bar
```

# DomainAccessAssociation
<a name="sam-property-api-domainaccessassociation"></a>

Configures a domain access association between an access association source and a private custom domain name. The only supported access association source is a VPC endpoint ID. For more information, see [Custom domain names for private APIs in API Gateway](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-private-custom-domains.html).

## Syntax
<a name="sam-property-api-domainaccessassociation-syntax"></a>

To declare this entity in your AWS Serverless Application Model (AWS SAM) template, use the following syntax.

### YAML
<a name="sam-property-api-domainaccessassociation-syntax.yaml"></a>

```
 VpcEndpointId: String
```

## Properties
<a name="sam-property-api-domainaccessassociation-properties"></a>

 `VpcEndpointId`   <a name="sam-api-domainaccessassociation-vpcendpointid"></a>
The endpoint ID of the VPC interface endpoint associated with the API Gateway VPC service.  
*Type*: String  
*Required*: Yes  
*CloudFormation compatibility*: This property is passed directly to the `[ AccessAssociationSource](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-domainnameaccessassociation.html#cfn-apigateway-domainnameaccessassociation-accessassociationsource)` property of an `AWS::ApiGateway::DomainNameAccessAssociation` resource.

# Route53Configuration
<a name="sam-property-api-route53configuration"></a>

Configures the Route53 record sets for an API.

## Syntax
<a name="sam-property-api-route53configuration-syntax"></a>

To declare this entity in your AWS Serverless Application Model (AWS SAM) template, use the following syntax.

### YAML
<a name="sam-property-api-route53configuration-syntax.yaml"></a>

```
  [DistributionDomainName](#sam-api-route53configuration-distributiondomainname): String
  [EvaluateTargetHealth](#sam-api-route53configuration-evaluatetargethealth): Boolean
  [HostedZoneId](#sam-api-route53configuration-hostedzoneid): String
  [HostedZoneName](#sam-api-route53configuration-hostedzonename): String
  [IpV6](#sam-api-route53configuration-ipv6): Boolean
  Region: String
  SetIdentifier: String
  VpcEndpointDomainName: String
  VpcEndpointHostedZoneId: String
```

## Properties
<a name="sam-property-api-route53configuration-properties"></a>

 `DistributionDomainName`   <a name="sam-api-route53configuration-distributiondomainname"></a>
Configures a custom distribution of the API custom domain name.  
*Type*: String  
*Required*: No  
*Default*: Use the API Gateway distribution.  
*CloudFormation compatibility*: This property is passed directly to the `[DNSName](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-route53-aliastarget-1.html#cfn-route53-aliastarget-dnshostname)` property of an `AWS::Route53::RecordSetGroup AliasTarget` resource.  
*Additional notes*: The domain name of a [CloudFront distribution](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-cloudfront-distribution.html).

 `EvaluateTargetHealth`   <a name="sam-api-route53configuration-evaluatetargethealth"></a>
When EvaluateTargetHealth is true, an alias record inherits the health of the referenced AWS resource, such as an Elastic Load Balancing load balancer or another record in the hosted zone.  
*Type*: Boolean  
*Required*: No  
*CloudFormation compatibility*: This property is passed directly to the `[EvaluateTargetHealth](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-route53-aliastarget.html#cfn-route53-aliastarget-evaluatetargethealth)` property of an `AWS::Route53::RecordSetGroup AliasTarget` resource.  
*Additional notes*: You can't set EvaluateTargetHealth to true when the alias target is a CloudFront distribution.

 `HostedZoneId`   <a name="sam-api-route53configuration-hostedzoneid"></a>
The ID of the hosted zone that you want to create records in.  
Specify either `HostedZoneName` or `HostedZoneId`, but not both. If you have multiple hosted zones with the same domain name, you must specify the hosted zone using `HostedZoneId`.  
*Type*: String  
*Required*: No  
*CloudFormation compatibility*: This property is passed directly to the `[HostedZoneId](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-route53-recordset-1.html#cfn-route53-recordset-hostedzoneid)` property of an `AWS::Route53::RecordSetGroup RecordSet` resource.

 `HostedZoneName`   <a name="sam-api-route53configuration-hostedzonename"></a>
The name of the hosted zone that you want to create records in.  
Specify either `HostedZoneName` or `HostedZoneId`, but not both. If you have multiple hosted zones with the same domain name, you must specify the hosted zone using `HostedZoneId`.  
*Type*: String  
*Required*: No  
*CloudFormation compatibility*: This property is passed directly to the `[HostedZoneName](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-route53-recordset-1.html#cfn-route53-recordset-hostedzonename)` property of an `AWS::Route53::RecordSetGroup RecordSet` resource.

 `IpV6`   <a name="sam-api-route53configuration-ipv6"></a>
When this property is set, AWS SAM creates a `AWS::Route53::RecordSet` resource and sets [Type](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-route53-recordset.html#cfn-route53-recordset-type) to `AAAA` for the provided HostedZone.  
*Type*: Boolean  
*Required*: No  
*CloudFormation compatibility*: This property is unique to AWS SAM and doesn't have an CloudFormation equivalent.

`Region`  <a name="sam-api-route53configuration-region"></a>
*Latency-based resource record sets only:* The Amazon EC2 Region where you created the resource that this resource record set refers to. The resource typically is an AWS resource, such as an EC2 instance or an ELB load balancer, and is referred to by an IP address or a DNS domain name, depending on the record type.  
When Amazon Route 53 receives a DNS query for a domain name and type for which you have created latency resource record sets, Route 53 selects the latency resource record set that has the lowest latency between the end user and the associated Amazon EC2 Region. Route 53 then returns the value that is associated with the selected resource record set.  
Note the following:  
+ You can only specify one `ResourceRecord` per latency resource record set.
+ You can only create one latency resource record set for each Amazon EC2 Region.
+ You aren't required to create latency resource record sets for all Amazon EC2 Regions. Route 53 will choose the region with the best latency from among the regions that you create latency resource record sets for.
+ You can't create non-latency resource record sets that have the same values for the `Name` and `Type` elements as latency resource record sets.
*Type*: String  
*Required*: No  
*CloudFormation compatibility*: This property is passed directly to the `[ Region](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-route53-recordset-1.html#cfn-route53-recordset-region)` property of an `AWS::Route53::RecordSetGroup` `RecordSet` data type.

`SetIdentifier`  <a name="sam-api-route53configuration-setidentifier"></a>
*Resource record sets that have a routing policy other than simple:* An identifier that differentiates among multiple resource record sets that have the same combination of name and type, such as multiple weighted resource record sets named acme.example.com that have a type of A. In a group of resource record sets that have the same name and type, the value of `SetIdentifier` must be unique for each resource record set.  
For information about routing policies, see [Choosing a routing policy](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/routing-policy.html) in the *Amazon Route 53 Developer Guide*.  
*Type*: String  
*Required*: No  
*CloudFormation compatibility*: This property is passed directly to the `[ SetIdentifier](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-route53-recordset-1.html#cfn-route53-recordset-setidentifier)` property of an `AWS::Route53::RecordSetGroup` `RecordSet` data type.

`VpcEndpointDomainName`  <a name="sam-api-route53configuration-vpcendpointdomainname"></a>
A DNS name of the VPC interface endpoint associated with the API Gateway VPC service. This property is required only for private domains.  
*Type*: String  
*Required*: No  
*CloudFormation compatibility*: This property is passed directly to the `[DNSName](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-route53-recordset-aliastarget.html)` property of an `AWS::Route53::RecordSet` `AliasTarget` field.

`VpcEndpointHostedZoneId`  <a name="sam-api-route53configuration-vpcendpointhostedzoneid"></a>
The hosted zone ID of the VPC interface endpoint associated with the API Gateway VPC service. This property is required only for private domains.  
*Type*: String  
*Required*: No  
*CloudFormation compatibility*: This property is passed directly to the `[HostedZoneId](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-route53-recordset-aliastarget.html)` property of an `AWS::Route53::RecordSet` `AliasTarget` field.

## Examples
<a name="sam-property-api-route53configuration--examples"></a>

### Basic example
<a name="sam-property-api-route53configuration--examples--route-53-configuration-example"></a>

In this example, we configure a custom domain and Route 53 record sets for our API.

#### YAML
<a name="sam-property-api-route53configuration--examples--route-53-configuration-example--yaml"></a>

```
Resources:
  MyApi:
    Type: AWS::Serverless::Api
    Properties:
      StageName: Prod
      Domain:
        DomainName: www.example.com
        CertificateArn: arn:aws:acm:us-east-1:123456789012:certificate/abcdef12-3456-7890-abcd-ef1234567890
        EndpointConfiguration: REGIONAL
        Route53:
          HostedZoneId: ABCDEFGHIJKLMNOP
```

# EndpointConfiguration
<a name="sam-property-api-endpointconfiguration"></a>

The endpoint type of a REST API.

## Syntax
<a name="sam-property-api-endpointconfiguration-syntax"></a>

To declare this entity in your AWS Serverless Application Model (AWS SAM) template, use the following syntax.

### YAML
<a name="sam-property-api-endpointconfiguration-syntax.yaml"></a>

```
  [IpAddressType](#sam-api-endpointconfiguration-ipaddresstype): String
  [Type](#sam-api-endpointconfiguration-type): String
  [VPCEndpointIds](#sam-api-endpointconfiguration-vpcendpointids): List
```

## Properties
<a name="sam-property-api-endpointconfiguration-properties"></a>

 `IpAddressType`   <a name="sam-api-endpointconfiguration-ipaddresstype"></a>
The IP address types that can invoke an API (RestApi).  
*Valid values*: `ipv4` or `dualstack`  
*Type*: String  
*Required*: No  
*CloudFormation compatibility*: This property is passed directly to the `[IpAddressType](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-apigateway-restapi-endpointconfiguration.html#cfn-apigateway-restapi-endpointconfiguration-ipaddresstype)` property of the `AWS::ApiGateway::RestApi` `EndpointConfiguration` data type.

 `Type`   <a name="sam-api-endpointconfiguration-type"></a>
The endpoint type of a REST API.  
*Valid values*: `EDGE` or `REGIONAL` or `PRIVATE`  
*Type*: String  
*Required*: No  
*CloudFormation compatibility*: This property is passed directly to the `[Types](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-apigateway-restapi-endpointconfiguration.html#cfn-apigateway-restapi-endpointconfiguration-types)` property of the `AWS::ApiGateway::RestApi` `EndpointConfiguration` data type.

 `VPCEndpointIds`   <a name="sam-api-endpointconfiguration-vpcendpointids"></a>
A list of VPC endpoint IDs of a REST API against which to create Route53 aliases.  
*Type*: List  
*Required*: No  
*CloudFormation compatibility*: This property is passed directly to the `[VpcEndpointIds](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-apigateway-restapi-endpointconfiguration.html#cfn-apigateway-restapi-endpointconfiguration-vpcendpointids)` property of the `AWS::ApiGateway::RestApi` `EndpointConfiguration` data type.

## Examples
<a name="sam-property-api-endpointconfiguration--examples"></a>

### EndpointConfiguration
<a name="sam-property-api-endpointconfiguration--examples--endpointconfiguration"></a>

Endpoint Configuration example

#### YAML
<a name="sam-property-api-endpointconfiguration--examples--endpointconfiguration--yaml"></a>

```
EndpointConfiguration:
  Type: PRIVATE
  VPCEndpointIds:
    - vpce-123a123a
    - vpce-321a321a
```