# 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 | List
```

## 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>
The Amazon Cognito user pool ARN(s) to use for authorization. Specify a single ARN as a string, or multiple ARNs as a list to use multiple user pools.  
*Type*: String \$1 List  
*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
```