• 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. Authentication

AppSync authentication

The appSync.authentication key sets the default authorization mode of an AppSync API, and appSync.additionalAuthentications adds more modes that clients can use instead. Use additional modes when different clients authenticate differently, for example a web app with Cognito user pools and a backend job with IAM.

This API accepts API keys by default and Cognito user pool tokens as an additional mode:

appSync:
  name: blog-api
  authentication:
    type: API_KEY
  additionalAuthentications:
    - type: AMAZON_COGNITO_USER_POOLS
      config:
        userPoolId: us-east-1_aBcDeFgHi
  apiKeys:
    - name: defaultKey

Each entry, in authentication and in the additionalAuthentications list, has two keys:

  • type: Required. API_KEY, AWS_IAM, AMAZON_COGNITO_USER_POOLS, OPENID_CONNECT or AWS_LAMBDA.
  • config: The settings for that type. Required for AMAZON_COGNITO_USER_POOLS, OPENID_CONNECT and AWS_LAMBDA; not used for API_KEY and AWS_IAM.

Rules for combining authorization modes

AppSync accepts API_KEY, AWS_LAMBDA and AWS_IAM at most once across authentication and additionalAuthentications. Cognito user pools and OpenID Connect providers can appear more than once, each with a different user pool or provider. When an API has additional modes, AppSync applies the default mode to every field, and you mark the fields and types that other modes may reach with directives in the schema, such as @aws_api_key, @aws_iam, @aws_cognito_user_pools, @aws_oidc and @aws_lambda (see the AWS guide linked in the opening).

API key authentication

The API_KEY type authorizes requests that send a valid key in the x-api-key header:

appSync:
  name: blog-api
  authentication:
    type: API_KEY
  apiKeys:
    - name: defaultKey

The Framework creates the keys listed in appSync.apiKeys only when API_KEY is the default or an additional mode; without apiKeys, it creates no key. Key names, expiry and per-key WAF rules are on the AppSync API keys page.

IAM authentication

The AWS_IAM type authorizes requests signed with AWS Signature Version 4 by an IAM user or role whose policy allows appsync:GraphQL on the API's fields:

appSync:
  name: blog-api
  authentication:
    type: AWS_IAM

Cognito user pool authentication

The AMAZON_COGNITO_USER_POOLS type authorizes requests that send a token issued by an Amazon Cognito user pool:

appSync:
  name: blog-api
  authentication:
    type: AMAZON_COGNITO_USER_POOLS
    config:
      userPoolId: us-east-1_aBcDeFgHi
      appIdClientRegex: '^my-app-client-id$'
      defaultAction: ALLOW

The config keys for Cognito user pools:

KeyTypeDefaultDescription
userPoolIdstring or intrinsicRequiredThe user pool ID, such as us-east-1_aBcDeFgHi, or !Ref to a user pool in resources.
awsRegionstring or intrinsicThe service's RegionThe Region of the user pool.
appIdClientRegexstring or intrinsicNoneA regular expression that the token's app client ID must match.
defaultActionALLOW or DENYALLOWWhat AppSync does with a valid token that doesn't match the user pool configuration. Applies only in authentication, not in additionalAuthentications. With additional modes, AppSync requires ALLOW.

OpenID Connect authentication

The OPENID_CONNECT type authorizes requests that send a token from a third-party OpenID Connect (OIDC) provider:

appSync:
  name: blog-api
  authentication:
    type: OPENID_CONNECT
    config:
      issuer: https://auth.example.com
      clientId: 5fbc318d-5920-48a8-92ea-20d62d16cc60

The config keys for OIDC:

KeyTypeDefaultDescription
issuerstringRequiredThe issuer URL, which must match the token's iss claim.
clientIdstringNoneThe client identifier of the relying party at the provider. A regular expression matches several client IDs.
iatTTLnumberNoneMilliseconds a token stays valid after it is issued.
authTTLnumberNoneMilliseconds a token stays valid after the user authenticates.

Lambda authorizer authentication

The AWS_LAMBDA type sends the request's Authorization header to a Lambda function that decides whether to allow it. This configuration defines the authorizer function inline:

provider:
  name: aws
  runtime: nodejs24.x

appSync:
  name: blog-api
  authentication:
    type: AWS_LAMBDA
    config:
      authorizerResultTtlInSeconds: 300
      function:
        handler: functions/authorizer.handler
        timeout: 10
        environment:
          EXPECTED_TOKEN: ${ssm:/blog-api/authorizer-token}

The handler in functions/authorizer.mjs returns isAuthorized and, optionally, values that resolvers read from ctx.identity.resolverContext:

export const handler = async (event) => {
  const token = event.authorizationToken

  return {
    isAuthorized: token === `Bearer ${process.env.EXPECTED_TOKEN}`,
    resolverContext: { client: 'internal' },
  }
}

The config keys for Lambda authorizers:

KeyTypeDefaultDescription
functionobjectNoneA function definition, with the same keys as an entry under functions. The Framework adds it to functions under the name <API name>Authorizer.
functionNamestringNoneThe key of a function defined under functions in the same serverless.yml.
functionAliasstringNoneAn alias of the functionName function to invoke.
functionArnstringNoneThe ARN of an existing function.
authorizerResultTtlInSecondsnumber, 0–36000 (AppSync default, no caching)Seconds AppSync caches the function's response. The function can override it per response with ttlOverride.
identityValidationExpressionstringNoneA regular expression the token must match before AppSync invokes the function.

Set exactly one of function, functionName or functionArn. The Framework adds a Lambda permission that lets appsync.amazonaws.com invoke the function from this API only. AppSync stops waiting for an authorizer after 10 seconds, so a longer function timeout doesn't help.

Related pages

  • AppSync API keys
  • AppSync WAF: rate limiting and blocking in front of any authorization mode
  • AppSync overview
Edit this page
Prev General ConfigurationNextAPI Keys

Contents

  • AppSync authentication
  • Rules for combining authorization modes
  • API key authentication
  • IAM authentication
  • Cognito user pool authentication
  • OpenID Connect authentication
  • Lambda authorizer authentication
  • Related pages

Related

GuidesPluginsExamplesSlack CommunitySupport