• Documentation
  • Pricing
© 2026 Serverless, Inc. All rights reserved.

Framework

  • Overview
  • Documentation
  • Plugins360
  • Pricing

Learn

  • Blog
  • GuidesUpdated
  • Examples240
  • Courses

Resources

  • Support
  • Security
  • Trust Center
  • Status

Community

  • Slack
  • GitHub47k
  • Forum
  • Meetups

Company

  • About
  • Careers
  • Contact
  • Partners

Legal

  • Terms of Service
  • Privacy Policy
  • Trademark
  • DMCA
Serverless Framework Logo

Serverless Framework

Intro
SetupUpgrading To V4ConceptsTutorialAWS CredentialsLicense Keys
DeployingPackagingBuildingTestingDev ModeServicesFunctions
OverviewHTTP (API Gateway v2)REST (API Gateway v1)ActiveMQApplication Load BalancerAlexa SkillAlexa Smart HomeCloudWatch EventCloudWatch LogCloudFrontCognito User PoolEventBridge EventIoTIoT Fleet ProvisioningKafkaKinesis & DynamoDBMSKRabbitMQS3ScheduleSNSSQSWebsocket
LayersManaged InstancesWeb Apps (Lambda Web Functions)Sandboxes (Lambda MicroVMs)MCP ServersAlertsVersion PruningDomainsIAM Function PermissionsParameters
OverviewSelf-reference serverless.ymlServerless CoreEnvironment VariablesCLI OptionsExternal YAML/JSON FilesJavascript propertiesGitDoppler
OverviewS3 ObjectsSSM Parameter Store & Secrets ManagerCloudFormation Stack Outputs
OverviewVaultTerraform State Output
ResourcesComposing ServicesDeployment BucketStateAgent SkillsPython support
OverviewRuntimeGatewayMemoryBrowserCode InterpreterDev Mode
API Gateway Proxy
OverviewGeneral ConfigurationAuthenticationAPI KeysData SourcesResolversPipeline FunctionsSubstitutionsCachingDelta SyncCustom DomainWAFCLI Commands
Deploying SAM/CFN TemplatesWorkflow Tips
OverviewCreating PluginsCLI OutputCustom CommandsCustom VariablesExtending the Configuration schemaExtending and overriding configuration
OverviewDashboardAxiom
Overviewagent docsagent inspectagent setupagent skills installagent skills list / readdeploydeploy functiondeploy listdevdiffinfoinvokeinvoke localloginlogin awslogin aws ssologsmetricspackageplugin installplugin uninstallprintprunereconcileremoverollbackrollback functionusage
OverviewConcepts
OverviewMetricsTracesTroubleshoot
OverviewNode.jsPython
OutputsProviders
OverviewBranch DeploymentsPreview DeploymentsCustom ScriptsTestingPrivate PackagesNotificationsMono ReposDeploy in your own CI/CDBest PracticesTroubleshootingFAQ
OverviewSetupToolsAWS Integration
Serverless.yml Reference
Examples and TutorialsConfiguration Validation
  1. Usage
  2. App Sync
  3. WAF

AppSync WAF

The appSync.waf block puts an AWS WAF (Web Application Firewall) web ACL in front of an AppSync API, so that WAF rules can block, allow, count or challenge requests before they reach your resolvers. The Framework creates a regional web ACL from the rules you list and associates it with the API, or associates a web ACL you already have. Ready-made rules cover per-IP rate limiting and introspection blocking; custom rules take any AWS WAF statement.

This configuration limits each IP address to 1000 requests per 5 minutes and blocks introspection queries:

appSync:
  name: blog-api
  waf:
    rules:
      - throttle: 1000
      - disableIntrospection

To associate an existing web ACL instead, set its ARN:

appSync:
  name: blog-api
  waf:
    arn: arn:aws:wafv2:us-east-1:123456789012:regional/webacl/blog-api-acl/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111

WAF keys

KeyTypeDefaultDescription
enabledbooleantrueSet to false to remove the web ACL and its association while keeping the block.
arnstring or intrinsicNoneThe ARN of an existing regional web ACL. With arn, the Framework creates only the association and ignores the other keys.
ruleslistRequired without arnThe rules, described in the following sections.
namestring<API name>WafThe web ACL name.
defaultActionAllow or BlockAllowWhat WAF does with a request that matches no rule.
descriptionstringACL rules for AppSync <API name>The web ACL description.
visibilityConfigobjectSee next tableCloudWatch metrics and request sampling for the web ACL, and the defaults for its rules.

visibilityConfig, on the web ACL and on each rule, takes these keys:

KeyTypeDefaultDescription
namestringThe web ACL's or rule's nameThe CloudWatch metric name.
cloudWatchMetricsEnabledbooleanThe web ACL's value, else trueSends metrics to CloudWatch.
sampledRequestsEnabledbooleanThe web ACL's value, else trueStores a sample of matching requests.

The web ACL is tagged with appSync.tags. AWS bills each web ACL, rule and request; see AWS WAF pricing.

Throttle rule

The throttle rule blocks an IP address that sends more than limit requests in 5 minutes, with an AWS WAF rate-based statement. It has three forms:

appSync:
  name: blog-api
  waf:
    rules:
      # 100 requests per 5 minutes per IP address
      - throttle
appSync:
  name: blog-api
  waf:
    rules:
      # 500 requests per 5 minutes per IP address
      - throttle: 500
appSync:
  name: blog-api
  waf:
    rules:
      # 500 requests per 5 minutes per client IP from a header, for clients behind a proxy
      - throttle:
          name: ThrottleByClientIp
          limit: 500
          priority: 10
          aggregateKeyType: FORWARDED_IP
          forwardedIPConfig:
            headerName: X-Forwarded-For
            fallbackBehavior: MATCH
KeyTypeDefaultDescription
limitinteger, at least 100100Requests allowed per IP address in a 5-minute window.
aggregateKeyTypeIP or FORWARDED_IPIPCounts requests by source IP, or by the IP address in a header.
forwardedIPConfig.headerNamestringRequired in forwardedIPConfigWith FORWARDED_IP: the header holding the client IP.
forwardedIPConfig.fallbackBehaviorMATCH or NO_MATCHRequired in forwardedIPConfigWith FORWARDED_IP: whether a request with an invalid IP address in the header counts as matching.
scopeDownStatementobjectNoneAn AWS WAF statement, in CloudFormation's PascalCase keys, that limits which requests the rule counts.
namestringThrottleThe rule name.
priorityintegerGeneratedSee Rules priority.
visibilityConfigobjectSee WAF keysMetrics and sampling for the rule.

When a FORWARDED_IP rule has no forwardedIPConfig, the Framework uses X-Forwarded-For as headerName and MATCH as fallbackBehavior. When you set forwardedIPConfig, set both keys; with only one of them, configuration validation reports must be a valid WAF rule: a warning by default, and an error that stops the command with configValidationMode: error.

A FORWARDED_IP throttle rule doesn't evaluate a request that lacks the header, so fallbackBehavior doesn't apply and the request isn't counted. Use FORWARDED_IP only when a proxy you control sets the header on every request, or add a rule that blocks requests without it.

A throttle rule's action is always Block. AWS WAF estimates request rates rather than counting them exactly, so it rate limits near limit, and requests over the limit can reach the API for up to several minutes before the block takes effect; see rate-based rule caveats.

Disable introspection rule

The disableIntrospection rule blocks GraphQL introspection queries that read the full schema through __schema:

appSync:
  name: blog-api
  waf:
    rules:
      - disableIntrospection

The rule blocks every request whose body contains __schema, and every request whose body is larger than 8 KB, the part of the body AWS WAF inspects for AppSync. A query that reads type details through __type without __schema passes the rule. To turn off all introspection, or if clients send larger requests, use the introspection: false API setting instead, which turns introspection off in AppSync itself. To set the rule's name, priority or visibilityConfig, use the object form:

appSync:
  name: blog-api
  waf:
    rules:
      - disableIntrospection:
          name: BlockIntrospection
          priority: 200

Custom rules

A custom rule takes any AWS WAF rule statement. This web ACL blocks all requests except those from the United States:

appSync:
  name: blog-api
  waf:
    defaultAction: Block
    rules:
      - name: UsOnly
        action: Allow
        statement:
          GeoMatchStatement:
            CountryCodes:
              - US
KeyTypeDefaultDescription
namestringRequiredThe rule name.
statementobjectRequiredAn AWS WAF rule statement. The Framework passes it to CloudFormation unchanged, so its keys use CloudFormation's PascalCase.
actionAllow, Block, Count or CaptchaAllowWhat WAF does with a matching request.
overrideActionobjectNoneFor rule group statements: replaces action, for example None: {} to apply the group's own actions.
prioritynumberGeneratedSee Rules priority.
visibilityConfigobjectSee WAF keysMetrics and sampling for the rule.

AWS managed rule groups

To use an AWS managed rule group, reference it in a ManagedRuleGroupStatement and set overrideAction: { None: {} } so the group's own rule actions apply:

appSync:
  name: blog-api
  waf:
    rules:
      - name: AWSManagedRulesCommonRuleSet
        priority: 20
        overrideAction:
          None: {}
        statement:
          ManagedRuleGroupStatement:
            VendorName: AWS
            Name: AWSManagedRulesCommonRuleSet

Per-API-key rules

The wafRules list of an entry in appSync.apiKeys adds rules that apply only to requests made with that key. They take the same forms as the web ACL's rules:

appSync:
  name: blog-api
  authentication:
    type: API_KEY
  waf:
    rules: []
  apiKeys:
    - name: partner
      wafRules:
        - throttle: 200
        - disableIntrospection

For each key rule, the Framework adds a match on the request's x-api-key header: combined with the rule's statement, or as the scope-down statement of a throttle rule. Default rule names get the key's name as a prefix (partnerThrottle). The rules join the same web ACL, so appSync.waf must be present.

Custom key rules need a statement, like other custom rules. To exempt a key from a global rule, give the key a rule with a lower priority number whose statement matches the requests the global rule would block. In this example, the web ACL blocks requests from outside the US, except requests with the worldwide key:

appSync:
  name: blog-api
  authentication:
    type: API_KEY
  waf:
    defaultAction: Block
    rules:
      - name: UsOnly
        action: Allow
        priority: 5
        statement:
          GeoMatchStatement:
            CountryCodes:
              - US
  apiKeys:
    - name: mobileApp # the UsOnly rule applies
    - name: worldwide
      wafRules:
        - name: AllowWorldwideKey
          action: Allow
          priority: 1 # evaluated before UsOnly (priority 5)
          statement:
            NotStatement:
              Statement:
                GeoMatchStatement:
                  CountryCodes:
                    - US

Rules priority

AWS WAF evaluates rules from the lowest priority number to the highest, and every rule in a web ACL needs a different priority. Rules without priority get one generated, starting at 100 and counting up: first the web ACL's rules in the order listed, then each API key's rules, in the order of the keys. Numbers 1 to 99 stay free for rules that must run first; a priority of 0 is treated as unset and gets a generated number.

Generated numbers don't skip numbers you set, so an explicit priority of 100 or more can collide with a generated one; set every priority explicitly, or keep explicit ones between 1 and 99. In this example, the comments show the priority each rule gets:

appSync:
  name: blog-api
  authentication:
    type: API_KEY
  waf:
    rules:
      - throttle # 100
      - name: UsOnly # 5
        priority: 5
        statement:
          GeoMatchStatement:
            CountryCodes:
              - US
      - disableIntrospection # 101
  apiKeys:
    - name: partner
      wafRules:
        - throttle: 200 # 102
        - disableIntrospection # 103

For how AWS WAF evaluates rules and actions, see Rule and rule group evaluation.

Related pages

  • AppSync API keys
  • AppSync authentication
  • AWS WAF integration in AWS AppSync
Edit this page
Prev Custom DomainNextCLI Commands

Contents

  • AppSync WAF
  • WAF keys
  • Throttle rule
  • Disable introspection rule
  • Custom rules
  • AWS managed rule groups
  • Per-API-key rules
  • Rules priority
  • Related pages

Related

GuidesPluginsExamplesSlack CommunitySupport