API Gateway

API Gateway exposes an HTTP API in front of your application and routes incoming requests to a Lambda function, an SQS queue, or a private ALB. It authenticates requests with a JWT (OneLogin) or Lambda authorizer before they reach the backend.

Byks guides

Lambda + API Gateway

Expose a Lambda function through an API Gateway HTTP API

Lambda + API Gateway

Terraform configuration

The api_gateway block configures one HTTP API Gateway for the application. Routes send requests to a Lambda function, an SQS queue, or a private ALB, optionally behind a JWT or Lambda authorizer.

main.tf

module "application" {
  source = "git@github.com:BYM-IKT/terraform-byks-module.git?ref=v12"
  # ...

  api_gateway = {
    # options go here
  }
}

Options

Option	Type	Default	Description
`description`	`string`	`null`	Description of the API Gateway.
`override_api_gateway_name`	`string`	`null`	Custom API Gateway name, instead of the generated `<environment>-<application_name>-api`.
`override_api_gateway_fqdn`	`string`	`null`	Custom fully qualified domain name, instead of the generated `<application_name>-api.<domain>`.
`override_log_format`	`string`	`null`	Custom access log format for the default stage, as a JSON string. Defaults to a format that includes the HTTP method, path, status, and request ID.
`cors_configuration`	`object`	`{}`	Cross-origin resource sharing settings. See CORS configuration object.
`authorizers`	`map(object)`	`{}`	JWT or Lambda request authorizers that routes can require. See JWT or Lambda authorizer object.
`integrations`	`object`	`null`	Backends that routes send requests to: Lambda functions, SQS queues, or private ALBs. Set it to at least `{}`. Omitting it entirely causes an error, since routes need at least one integration to target. See Integrations object.
`routes`	`map(object)`	`{}`	Routes exposed by the API Gateway, keyed `METHOD /path` (for example `GET /cats`), or `$default`. See Route object.

CORS configuration object

Used in cors_configuration.

Option	Type	Default	Description
`allow_credentials`	`bool`	`null`	Allow requests to include credentials.
`allow_headers`	`set(string)`	`null`	Headers allowed in a request.
`allow_methods`	`set(string)`	`null`	HTTP methods allowed in a request.
`allow_origins`	`set(string)`	`null`	Origins allowed to call the API.
`expose_headers`	`set(string)`	`null`	Headers exposed to the caller.
`max_age`	`number`	`null`	Seconds browsers cache the preflight response.

JWT or Lambda authorizer object

Used in authorizers. The map key is an arbitrary name, referenced by routes through their authorizer field.

Option	Type	Default	Description
`identity_sources`	`list(string)`	`["$request.header.Authorization"]`	Request locations API Gateway checks to identify the caller.
`jwt_configuration`	`object`	`null`	JWT authorizer settings, for JWT-based auth such as OneLogin. Set exactly one of `jwt_configuration` or `request_configuration` per authorizer. See JWT configuration object.
`request_configuration`	`object`	`null`	Lambda request authorizer settings. Set exactly one of `jwt_configuration` or `request_configuration` per authorizer. See Request configuration object.

JWT configuration object

Used in authorizers.*.jwt_configuration.

Option	Type	Default	Description
`audience`	`list(string)`	required	Allowed audience values (client IDs) from the JWT.
`issuer`	`string`	required	Issuer URL of the identity provider, typically `https://oslo.onelogin.com/oidc/2` (prod) or `https://sandbox-oslo.onelogin.com/oidc/2` (test/dev).

Request configuration object

Used in authorizers.*.request_configuration. Configures the Lambda function that backs a request authorizer, either from a container image or a zip package.

Option	Type	Default	Description
`image_repo_url`	`string`	`null`	ECR repository to fetch the authorizer image from. Not applicable if `code_source` is set.
`image_tag`	`string`	`null`	Image tag to fetch from the container repository. Not applicable if `code_source` is set.
`image_command`	`list(string)`	`null`	Container entrypoint command to run. Not applicable if `code_source` is set.
`authorizer_result_ttl_in_seconds`	`number`	`null`	Seconds API Gateway caches the authorizer's response.
`enable_simple_responses`	`bool`	`null`	Return a `true`/`false` or string response instead of a full IAM policy document.
`environment_variables`	`map(string)`	`null`	Environment variables passed to the authorizer function.
`code_runtime`	`string`	`null`	Lambda runtime for the authorizer. Not applicable if `image_repo_url` is set.
`code_upload_bucket`	`string`	`null`	S3 bucket the code bundle is uploaded to. Not required, but recommended for larger bundles. Not applicable if `image_repo_url` is set.
`lambda_handler`	`string`	`null`	Function handler to run. Not applicable if `image_repo_url` is set.
`memory_size`	`number`	`128`	Memory, in MB, allocated to the authorizer function. Also determines the allocated vCPU.
`function_timeout`	`number`	`5`	Seconds before the authorizer function times out.
`ephemeral_storage_size_mb`	`number`	`512`	Ephemeral storage, in MB, allocated to the authorizer function.
`code_source`	`object`	`null`	Deployment package to upload. Not applicable if `image_repo_url` is set. See Code source object.

Code source object

Used in authorizers.*.request_configuration.code_source.

Option	Type	Default	Description
`bundle_base64sha256`	`string`	required	Pre-calculated SHA256 checksum of the deployment package.
`bundle_path`	`string`	required	Path to the zip file.

Integrations object

Used in integrations. Groups the backends routes can target, by type.

Option	Type	Default	Description
`lambda_functions`	`map(object)`	`{}`	Routes requests to a Lambda function. See Lambda function integration object.
`sqs_queues`	`map(object)`	`{}`	Sends requests as messages to an SQS queue. See SQS queue integration object.
`private_albs`	`map(object)`	`{}`	Routes requests to a private ALB over a VPC link. See Private ALB integration object.

Lambda function integration object

Used in integrations.lambda_functions. The map key is an arbitrary integration name, referenced by routes through their target_integration field. Integration keys must be unique across lambda_functions, sqs_queues, and private_albs.

Option	Type	Default	Description
`lambda_function_id`	`string`	required	Key of the function in `lambda_functions` this integration invokes.
`description`	`string`	`null`	Description of the integration.
`integration_method`	`string`	`"POST"`	HTTP method used internally for the integration. Lambda proxy integrations always use `POST`.
`payload_format_version`	`string`	`"2.0"`	Payload format version sent to the function. `2.0` is recommended for HTTP APIs.
`timeout_milliseconds`	`number`	`30000`	Milliseconds before the integration times out.

SQS queue integration object

Used in integrations.sqs_queues. The map key is an arbitrary integration name, referenced by routes through their target_integration field. Integration keys must be unique across lambda_functions, sqs_queues, and private_albs.

Option	Type	Default	Description
`sqs_queue_id`	`string`	required	Key of the queue in `sqs_queues` this integration sends messages to.
`description`	`string`	`null`	Description of the integration.
`integration_subtype`	`string`	`"SQS-SendMessage"`	AWS service action the integration calls. See AWS service integrations for HTTP APIs.
`additional_request_parameters`	`map(string)`	`{ MessageBody = "$request.body" }`	Extra request parameters merged into the SQS `SendMessage` call, alongside the queue URL.
`timeout_milliseconds`	`number`	`30000`	Milliseconds before the integration times out.

Private ALB integration object

Used in integrations.private_albs. The map key is an arbitrary integration name, referenced by routes through their target_integration field. Integration keys must be unique across lambda_functions, sqs_queues, and private_albs.

Option	Type	Default	Description
`description`	`string`	`null`	Description of the integration.
`timeout_milliseconds`	`number`	`30000`	Milliseconds before the integration times out.
`alb`	`object`	required	ALB listener to route to. Accepts the ALB module's output directly. See ALB object.
`tls_config`	`object`	`null`	TLS settings for the connection to the ALB. See TLS configuration object.

ALB object

Used in integrations.private_albs.*.alb.

Option	Type	Default	Description
`listener_arn`	`string`	required	ARN of the ALB listener to route to.
`alb_sg_id`	`string`	required	Security group ID of the ALB, used to allow traffic from the VPC link.

TLS configuration object

Used in integrations.private_albs.*.tls_config.

Option	Type	Default	Description
`server_name_to_verify`	`string`	required	Server name to verify against the ALB's TLS certificate.

Route object

Used in routes. The map key is the route, in the form METHOD /path (for example GET /cats), or the special key $default.

Option	Type	Default	Description
`target_integration`	`string`	required	Key of the integration in `integrations.lambda_functions`, `integrations.sqs_queues`, or `integrations.private_albs` this route sends requests to.
`authorizer`	`string`	`null`	`AWS_IAM`, `NONE`, or the name of an authorizer defined in `authorizers`.
`authorization_scopes`	`list(string)`	`null`	Scopes required by the route. Only applicable for JWT authorizers.

Resources

AWS documentation

Official AWS documentation for API Gateway

AWS documentation