HttpApi

An API Gateway HTTP API with throttling, one-year access logs and strict CORS by default. Add a custom domain or protect every route in one line.

API & Auth · anvil:aws:HttpApi

Arguments

Names below are TypeScript (camelCase). In Python use snake_case (e.g. dataClassification → data_classification); in Go use PascalCase on the Args struct (e.g. DataClassification).

routes required
array

The API routes. Each route maps a method and path to a consumer. At least one route is required.

defaultAuthorizerId
Output<string>

The JWT authorizer to apply to all routes. Pass authorizerId from an OAuthAuthorizer or CognitoAuth component — HttpApi creates the API Gateway authorizer on this API, since authorizers can't be shared between APIs. All routes inherit it unless skipAuth: true is set on the route. Omit to leave all routes public.

domain
object (HttpApiDomain)

Optional custom domain for the API. When set, Anvil provisions the ACM certificate, API Gateway domain name, and Route 53 DNS record automatically. The raw execute-api endpoint is disabled — all traffic must flow through the custom domain.

cors
object (HttpApiCors)

Optional CORS configuration. Opt-in — omit to disable CORS entirely. When enabled, allowOrigins is required and wildcard '*' is blocked as a security measure.

throttling
object (HttpApiThrottling)

Optional throttling configuration. Defaults to rateLimit: 1000 rps and burstLimit: 500 concurrent requests when omitted.

logRetention
string

CloudWatch access log retention period. Default: '1y' — satisfies SOC 2, ISO 27001, and PCI DSS baseline retention requirements.

  • 7d— 7 days
  • 30d— 30 days
  • 90d— 90 days
  • 1y— 1 year — default
  • 3y— 3 years
  • 6y— 6 years
  • 7y— 7 years
routes[] 6 fields

A single route on the HTTP API mapping a method and path to a consumer target.

method required
string

The HTTP method for this route.

  • GET— HTTP GET — read operations.
  • POST— HTTP POST — create operations and async consumers (SQS, EventBridge, Step Functions).
  • PUT— HTTP PUT — replace operations.
  • PATCH— HTTP PATCH — partial update operations.
  • DELETE— HTTP DELETE — delete operations.
  • ANY— Matches all HTTP methods. Maps to the $default route key.
path required
string

The route path. e.g. '/users' or '/users/{id}'. Use {param} for path parameters and {proxy+} for greedy paths.

consumer required
object (HttpApiRouteConsumer)

The target that handles this route. Exactly one consumer type must be set.

skipAuth
boolean

Explicitly opt this route out of the API-level defaultAuthorizer. Use for health checks, webhook endpoints, or any route that handles its own validation. Has no effect if defaultAuthorizerId is not set.

scopes
array<string>

OAuth scopes required to access this route. API Gateway rejects tokens that do not contain all listed scopes. Only applies when defaultAuthorizerId is set and skipAuth is false. Example: ['read:users', 'write:orders'].

throttling
object (HttpApiThrottling)

Optional per-route throttling override. Inherits API-level throttling when omitted.

routes[].consumer 5 fields

The target that handles a route. Exactly one field must be set — Anvil validates this at deploy time and returns a clear error if zero or multiple are set.

lambda
object (HttpApiLambdaConsumer)

Route to a Lambda function. Pass lambda.arn directly.

sqs
object (HttpApiSqsConsumer)

Route directly to an SQS queue. No Lambda required. Returns 202 Accepted immediately — message is processed asynchronously. Must use POST, PUT, or PATCH.

eventBridge
object (HttpApiEventBridgeConsumer)

Route directly to an EventBridge bus. No Lambda required. Must use POST, PUT, or PATCH.

stepFunctions
object (HttpApiStepFunctionsConsumer)

Route to a Step Functions state machine. Async by default. Must use POST, PUT, or PATCH.

http
object (HttpApiHttpConsumer)

Proxy to an external HTTP URL. Useful for gradual migration from legacy APIs.

routes[].consumer.lambda 1 field

Routes requests to a Lambda function via AWS_PROXY integration. API Gateway invokes the Lambda synchronously and returns its response directly.

arn required
string

The Lambda function ARN. Pass lambda.arn directly. Accepts Output<string>.

routes[].consumer.sqs 2 fields

Routes requests directly to an SQS queue. API Gateway sends the request body as a message — no Lambda required. Returns 202 Accepted immediately. Anvil creates a least-privilege IAM role granting sqs:SendMessage on this queue only.

url required
string

The SQS queue URL. Pass queue.url directly. Accepts Output<string>.

arn required
string

The SQS queue ARN. Pass queue.arn directly. Accepts Output<string>.

routes[].consumer.eventBridge 1 field

Routes requests directly to an EventBridge bus. API Gateway puts the request body as an event — no Lambda required. Anvil creates a least-privilege IAM role granting events:PutEvents on this bus only.

name required
string

The EventBridge bus name. Pass bus.name directly. Accepts Output<string>.

routes[].consumer.stepFunctions 2 fields

Routes requests to a Step Functions state machine. Async by default (StartExecution). Set sync: true for StartSyncExecution — note the 29s API Gateway timeout applies. Anvil creates a least-privilege IAM role granting the appropriate Start action on this state machine only.

arn required
string

The state machine ARN. Pass stateMachine.arn directly. Accepts Output<string>.

sync
boolean

Wait for execution to complete before responding. Default: false (async). Only use for fast state machines — subject to the 29s API Gateway timeout.

routes[].consumer.http 1 field

Proxies requests to an external HTTP URL. Useful for gradual migration from legacy APIs or third-party integrations. No IAM configuration required.

url required
string

The external HTTP URL to proxy to. e.g. 'https://legacy-api.mycompany.com'.

routes[].throttling 2 fields

Rate and burst throttling limits. Applied at the API level by default — individual routes can override. Defaults: rateLimit 1000 rps, burstLimit 500 concurrent. Without throttling a single route can exhaust the account-level limit (10,000 rps) shared across all APIs in the account.

rateLimit
integer

Maximum sustained requests per second. Default: 1000.

burstLimit
integer

Maximum concurrent requests (token bucket capacity). Default: 500.

domain 5 fields

Custom domain configuration. When set, Anvil provisions the ACM certificate (with DNS validation), API Gateway domain name resource, and Route 53 A alias record. TLS 1.2 minimum is always enforced. The execute-api endpoint is disabled when a domain is set. Set dns: false for Cloudflare or other non-Route 53 providers.

name required
string

The fully qualified domain name. e.g. 'api.mysite.com'.

basePath
string

Optional API mapping base path. e.g. 'v1' makes the API accessible at https://name/v1. Omit for root path mapping.

certificateArn
string

BYO ACM certificate ARN. When omitted Anvil creates and validates the certificate automatically via DNS validation. Required when dns: false to skip Route 53 cert validation entirely.

zoneId
string

Route 53 hosted zone ID. When omitted Anvil discovers the zone by domain name automatically. Ignored when dns: false.

dns
boolean

Create Route 53 DNS and cert validation records automatically. Default: true. Set to false for Cloudflare or other non-Route 53 DNS providers — Anvil will output the API Gateway target domain and (when certificateArn is omitted) the ACM validation CNAME for manual configuration.

cors 5 fields

Cross-Origin Resource Sharing configuration. Opt-in — omit to disable CORS. Security rules: allowOrigins '*' is blocked, allowCredentials requires explicit origins, allowMethods is inferred from routes when omitted.

allowOrigins required
array<string>

Allowed origins. Required when CORS is enabled. Wildcard '*' is blocked — specify explicit origins. e.g. ['https://app.mysite.com'].

allowHeaders
array<string>

Allowed request headers. Default: ['Content-Type', 'Authorization', 'X-Request-ID'].

allowMethods
array<string>

Allowed HTTP methods. Default: inferred automatically from the routes declared on this API.

allowCredentials
boolean

Allow cookies and auth headers in cross-origin requests. Default: false. When true, allowOrigins must not contain '*' — browsers reject this combination per the CORS specification.

maxAge
integer

Preflight cache duration in seconds. Default: 86400 (24 hours) — reduces preflight requests significantly.

throttling 2 fields

Rate and burst throttling limits. Applied at the API level by default — individual routes can override. Defaults: rateLimit 1000 rps, burstLimit 500 concurrent. Without throttling a single route can exhaust the account-level limit (10,000 rps) shared across all APIs in the account.

rateLimit
integer

Maximum sustained requests per second. Default: 1000.

burstLimit
integer

Maximum concurrent requests (token bucket capacity). Default: 500.

Attributes

Outputs available once the resource is deployed.

apiId
string

The API Gateway HTTP API ID.

apiEndpoint
string

The default execute-api endpoint URL. Empty string when a custom domain is set.

url
string

The primary URL for the API — the custom domain URL when configured, otherwise the execute-api endpoint URL.

certValidationCname
object (HttpApiCertValidationCname)

ACM cert validation CNAME. Only populated when domain.dns: false and domain.certificateArn is omitted. Add this record with your DNS provider and re-run deploy.