• 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. Events
  3. HTTP API Gateway V 2

HTTP API Events (API Gateway v2)

The httpApi event exposes a Lambda function at an HTTP route of an Amazon API Gateway HTTP API (API Gateway v2). The Framework creates one HTTP API per service, or uses an existing HTTP API, and a route for each event. HTTP APIs cost less than REST APIs and have fewer features; for API keys, usage plans, request validation or mapping templates, use the http event and a REST API. AWS compares the two in Choose between REST APIs and HTTP APIs.

This serverless.yml creates an HTTP API with a GET /hello route:

# serverless.yml
service: my-service

provider:
  name: aws
  runtime: nodejs24.x

functions:
  hello:
    handler: handler.hello
    events:
      - httpApi:
          method: GET
          path: /hello
// handler.mjs
export const hello = async (event) => {
  return {
    statusCode: 200,
    body: JSON.stringify({ message: 'Hello', path: event.rawPath }),
  }
}

serverless deploy and serverless info print the API's URL under endpoints. The URL is also in the HttpApiUrl stack output, and the API ID in HttpApiId. The Framework deploys the API's $default stage with automatic deployment, so the URL has no stage path: https://<api-id>.execute-api.<region>.amazonaws.com/hello.

Routes

A route is an HTTP method and a path. The httpApi event takes a route as a string, '<METHOD> <path>', or as method and path keys:

functions:
  simple:
    handler: handler.simple
    events:
      - httpApi: 'PATCH /elo'
  extended:
    handler: handler.extended
    events:
      - httpApi:
          method: POST
          path: /post/just/to/this/path

method is GET, POST, PUT, PATCH, OPTIONS, HEAD, DELETE, ANY or *, in any case; * is the same as ANY. path starts with /. Two events with the same method and path stop the deploy with Duplicate route '<METHOD> <path>' configuration in function <function> for httpApi event in serverless.yml.

Path parameters

A path segment in braces is a path parameter. The function receives its value in event.pathParameters:

functions:
  params:
    handler: handler.params
    events:
      - httpApi:
          method: GET
          path: /get/for/any/{param}

A greedy parameter such as {proxy+} matches the rest of the path.

Catch-all routes

httpApi: '*' creates the API's $default route, which receives every request that no other route matches. method: '*' matches any method on one path:

functions:
  catchAllAny:
    handler: handler.catchAllAny
    events:
      - httpApi: '*'
  catchAllMethod:
    handler: handler.catchAllMethod
    events:
      - httpApi:
          method: '*'
          path: /any/method

Endpoint timeout

The Framework sets the integration timeout of every route to 30 seconds, the HTTP API maximum, which can't be increased. A function that runs longer still completes, but the client gets an error response. The Framework prints a warning when a function with httpApi events has a timeout of 30 seconds or more; keep the function timeout below 30.

CORS setup

HTTP APIs answer CORS preflight requests themselves, with one configuration for all routes. To turn on CORS with the defaults, set provider.httpApi.cors to true:

provider:
  name: aws
  httpApi:
    cors: true

cors: true sends these headers:

HeaderValue
Access-Control-Allow-Origin*
Access-Control-Allow-HeadersContent-Type, X-Amz-Date, Authorization, X-Api-Key, X-Amz-Security-Token, X-Amz-User-Agent, X-Amzn-Trace-Id
Access-Control-Allow-MethodsOPTIONS and the methods of the service's routes; an ANY route adds every method

To set the headers yourself, use the object form:

provider:
  name: aws
  httpApi:
    cors:
      allowedOrigins:
        - https://url1.com
        - https://url2.com
      allowedHeaders:
        - Content-Type
        - Authorization
      allowedMethods:
        - GET
      allowCredentials: true
      exposedResponseHeaders:
        - Special-Response-Header
      maxAge: 6000 # In seconds

In the object form, allowedOrigins defaults to *, allowedHeaders to the headers of cors: true, and allowedMethods to OPTIONS plus the methods of the service's routes. allowCredentials defaults to false, and maxAge is an integer of 0 or more.

JWT authorizers

A JWT authorizer validates a JSON Web Token, such as one from an Amazon Cognito user pool, before API Gateway invokes the function. AWS describes the checks in Control access to HTTP APIs with JWT authorizers.

Define the authorizer under provider.httpApi.authorizers:

provider:
  name: aws
  httpApi:
    authorizers:
      someJwtAuthorizer:
        type: jwt
        identitySource: $request.header.Authorization
        issuerUrl: https://cognito-idp.us-east-1.amazonaws.com/us-east-1_EXAMPLE
        audience:
          - 1example23456789
          - 2example34567890

identitySource, issuerUrl and audience are required. type: jwt is optional: an authorizer without type is a JWT authorizer. name sets the authorizer's name in API Gateway (default: the key under authorizers). For a Cognito user pool, issuerUrl is https://cognito-idp.<region>.amazonaws.com/<user pool ID> and audience lists the app client IDs. API Gateway matches audience against the token's aud claim, or its client_id claim when the token has no aud, so the app client IDs match both Cognito ID tokens and access tokens.

Then reference it in the httpApi event's authorizer, with the scopes the route requires:

functions:
  someFunction:
    handler: handler.someFunction
    events:
      - httpApi:
          method: POST
          path: /some-post
          authorizer:
            name: someJwtAuthorizer
            scopes: # Optional
              - user.id
              - user.email

A route with scopes accepts a token whose scope or scp claim contains at least one of them. authorizer: someJwtAuthorizer (a string) is the same as authorizer: { name: someJwtAuthorizer }. A name that isn't defined under provider.httpApi.authorizers stops the deploy with Event references not configured authorizer '<name>'.

After API Gateway validates the token, the function receives its claims in event.requestContext.authorizer.jwt.claims (payload format '2.0'), for example the Cognito user ID in event.requestContext.authorizer.jwt.claims.sub.

Lambda (request) authorizers

A Lambda authorizer runs a function that decides whether API Gateway invokes the route. AWS describes the request and response formats in Control access to HTTP APIs with AWS Lambda authorizers.

To use a function of the service as the authorizer, define the authorizer with type: request and the function's name in functionName:

provider:
  name: aws
  httpApi:
    authorizers:
      customAuthorizer:
        type: request
        functionName: authorizerFunc

functions:
  hello:
    handler: handler.hello
    events:
      - httpApi:
          method: get
          path: /hello
          authorizer:
            name: customAuthorizer
  authorizerFunc:
    handler: authorizer.handler

To use a function outside the service, give its ARN in functionArn instead:

provider:
  name: aws
  httpApi:
    authorizers:
      customAuthorizer:
        type: request
        functionArn: arn:aws:lambda:us-east-1:123456789012:function:external-authorizer

The Framework creates the permission that lets API Gateway invoke the authorizer function, unless managedExternally is true.

Lambda authorizer settings

A request authorizer under provider.httpApi.authorizers accepts these keys:

KeyDefaultDescription
typeRequiredrequest.
functionName-A function of the service. A name that isn't a function of the service stops the deploy.
functionArn-The ARN of any function; accepts CloudFormation intrinsic functions. Set exactly one of functionName and functionArn.
nameThe keyThe authorizer's name in API Gateway.
identitySourceNoneOne or more identity sources, such as $request.header.Auth. API Gateway returns 401 without invoking the authorizer when one is missing. Required when resultTtlInSeconds is above 0, because it is the cache key.
resultTtlInSecondsAPI Gateway'sSeconds to cache the authorizer's result, 0 (no caching) to 3600.
enableSimpleResponsesfalseLets the function return { "isAuthorized": true } instead of an IAM policy.
payloadVersion'2.0'The event format sent to the authorizer, '1.0' or '2.0'.
managedExternallyfalseWith true, the Framework doesn't create the invoke permission, for example for a function in another AWS account. The permission must exist before you deploy.

This example sets all of them:

provider:
  name: aws
  httpApi:
    authorizers:
      customAuthorizer:
        type: request
        functionArn: arn:aws:lambda:us-east-1:123456789012:function:external-authorizer
        name: customAuthorizerName
        resultTtlInSeconds: 300
        enableSimpleResponses: true
        payloadVersion: '2.0'
        identitySource:
          - $request.header.Auth
          - $request.header.Authorization
        managedExternally: true

AWS IAM authorization

To require callers to sign requests with AWS credentials (IAM authorization), set the httpApi event's authorizer.type to aws_iam:

functions:
  hello:
    handler: handler.hello
    events:
      - httpApi:
          method: get
          path: /hello
          authorizer:
            type: aws_iam

With type: aws_iam, the authorizer takes no other keys; name, id or scopes stop the deploy. Callers need execute-api:Invoke on the route.

Access logs

To turn on access logs for the API's stage, set provider.logs.httpApi to true:

provider:
  name: aws
  logs:
    httpApi: true

Without logs.httpApi, the stage has no access logs. The Framework creates the log group /aws/http-api/<stack name> (by default /aws/http-api/<service>-<stage>) and points the stage's access logs at it. The log group keeps logs for provider.logRetentionInDays days when that is set, and indefinitely otherwise. HTTP API access logs don't use the account-level CloudWatch role that REST API execution logs need; the identity that deploys needs the CloudWatch Logs permissions in Configure logging for HTTP APIs. The default format is:

{
  "requestId": "$context.requestId",
  "ip": "$context.identity.sourceIp",
  "requestTime": "$context.requestTime",
  "httpMethod": "$context.httpMethod",
  "routeKey": "$context.routeKey",
  "status": "$context.status",
  "protocol": "$context.protocol",
  "responseLength": "$context.responseLength"
}

To change it, set format to a string with the variables for access logs you need:

provider:
  name: aws
  logs:
    httpApi:
      format: '{ "ip": "$context.identity.sourceIp", "requestTime":"$context.requestTime" }'

Event payload format

HTTP APIs send Lambda functions events in payload format '2.0' by default. Format '1.0' adds multiValueHeaders and multiValueQueryStringParameters, and its response format differs. To change the format for every function, set provider.httpApi.payload:

provider:
  name: aws
  httpApi:
    payload: '1.0'

To change it for one function, set httpApi.payload on the function; it takes precedence over provider.httpApi.payload:

functions:
  hello:
    handler: handler.hello
    httpApi:
      payload: '1.0'
    events:
      - httpApi:
          path: /hello
          method: GET

Allowed values are '1.0' and '2.0', as strings.

Detailed metrics

To turn on detailed CloudWatch metrics for each route (default: off), set provider.httpApi.metrics:

provider:
  name: aws
  httpApi:
    metrics: true

Tags

The Framework applies provider.tags to the HTTP API it creates and to the API's stage:

provider:
  name: aws
  tags:
    project: myProject

With provider.tags set, tags added to the API outside the Framework are removed on the next deploy. provider.httpApi.useProviderTags is deprecated and has no effect; remove it.

API name

The Framework names the HTTP API <stage>-<service>. To name it <service>-<stage>, set provider.httpApi.shouldStartNameWithService to true. To choose the name, set provider.httpApi.name, which takes precedence:

provider:
  name: aws
  httpApi:
    name: my-custom-api-name

Disable default endpoint

Clients can call the API at its execute-api URL. To allow calls only through a custom domain, set provider.httpApi.disableDefaultEndpoint to true:

provider:
  name: aws
  httpApi:
    disableDefaultEndpoint: true

Reuse an HTTP API from another service

To add the service's routes to an HTTP API that another service or stack manages, set provider.httpApi.id to the API's ID:

provider:
  name: aws
  httpApi:
    id: a1b2c3d4e5

id also accepts Fn::ImportValue with the name of a CloudFormation export that holds the ID:

provider:
  name: aws
  httpApi:
    id:
      Fn::ImportValue: my-shared-http-api-id

The Framework then creates the routes, integrations and permissions, but not the API, its stage, or the HttpApiId and HttpApiUrl outputs. The routes reach clients through a stage of that API with automatic deployment, or after you deploy that API's stage yourself. The API-level settings stop the deploy with an error: provider.httpApi.cors with Cannot setup CORS rules for externally configured HTTP API, provider.httpApi.authorizers with Cannot setup authorizers for externally configured HTTP API, and provider.logs.httpApi with Cannot setup access logs for externally configured HTTP API.

Shared authorizer

With provider.httpApi.id, a route can use an authorizer that already exists on that API: set the httpApi event's authorizer.id to the authorizer's ID and type to jwt or request. Without type, the route uses it as a JWT authorizer. authorizer.id without provider.httpApi.id stops the deploy with Event references external authorizer '<id>', but httpApi is part of the current stack.

This example creates a JWT authorizer on the shared API under resources and uses it for two routes:

provider:
  name: aws
  httpApi:
    id: a1b2c3d4e5

functions:
  createUser:
    handler: users.create
    events:
      - httpApi:
          path: /users
          method: post
          authorizer:
            type: jwt
            id:
              Ref: ApiGatewayAuthorizer # or the authorizer ID
            scopes: # Optional
              - myapp/myscope
  deleteUser:
    handler: users.delete
    events:
      - httpApi:
          path: /users/{userId}
          method: delete
          authorizer:
            type: jwt
            id:
              Ref: ApiGatewayAuthorizer
            scopes:
              - myapp/anotherscope

resources:
  Resources:
    ApiGatewayAuthorizer:
      Type: AWS::ApiGatewayV2::Authorizer
      Properties:
        ApiId: a1b2c3d4e5
        Name: shared-jwt
        AuthorizerType: JWT
        IdentitySource:
          - $request.header.Authorization
        JwtConfiguration:
          Audience:
            - 1example23456789
          Issuer: https://cognito-idp.us-east-1.amazonaws.com/us-east-1_EXAMPLE

Custom domains

API Gateway serves an HTTP API at https://<api-id>.execute-api.<region>.amazonaws.com/. To serve it at your own domain name, set provider.domain; the Framework reuses or requests the ACM certificate and creates the API Gateway custom domain, the API mapping and the Route 53 records:

provider:
  name: aws
  domain: api.example.com

The domain maps to the $default stage of the HTTP API that the service creates, not to an API set with provider.httpApi.id. When the service also has http (REST) or websocket events, use the object form, domain: { name: api.example.com, apiType: http }, as API types shows; without apiType the deploy stops with Multiple API types detected in CloudFormation template. Custom domains explains the certificate lookup, DNS outside Route 53 and every option. To set the domain up yourself instead, create an ACM certificate in the service's Region, create the custom domain name in API Gateway with an API mapping to the API's $default stage, then point a DNS record at the domain's API Gateway domain name (d-<id>.execute-api.<region>.amazonaws.com).

Related

  • HTTP API settings in the serverless.yml reference
  • REST API events: the http event and API Gateway v1.
  • Custom domains
Edit this page
Prev OverviewNextREST (API Gateway v1)

Contents

  • HTTP API Events (API Gateway v2)
  • Routes
  • Path parameters
  • Catch-all routes
  • Endpoint timeout
  • CORS setup
  • JWT authorizers
  • Lambda (request) authorizers
  • Lambda authorizer settings
  • AWS IAM authorization
  • Access logs
  • Event payload format
  • Detailed metrics
  • Tags
  • API name
  • Disable default endpoint
  • Reuse an HTTP API from another service
  • Shared authorizer
  • Custom domains
  • Related

Related

GuidesPluginsExamplesSlack CommunitySupport