AWS API Gateway for Regulated Workloads: VPC Integration, WAF & Custom Authorisers

Overview & service types

AWS API Gateway comes in three flavours that are not interchangeable:

• REST API — the original product. Feature-complete: stages, deployment history, per-method throttling, request/response mapping templates (VTL), usage plans with API keys, X-Ray integration. Higher per-call cost. Supports edge-optimised, regional, and private endpoints.
• HTTP API — launched in 2019, roughly 70% cheaper per call than REST API. Supports JWT authorisers natively, auto-deploy, VPC links to Application Load Balancers and Cloud Map. Missing: usage plans, API keys, per-method throttling, WAF direct attachment (WAF attaches to the CloudFront distribution in front). Best fit for internal microservice backends and workloads where latency cost is critical.
• WebSocket API — stateful bidirectional connections. Not covered here; distinct architecture requirements.

For a regulated financial-services environment, the choice almost always comes down to REST API with a private or regional endpoint. The feature set — usage plans, per-method throttling, request validation, VTL transforms, native WAF attachment — is what a SAMA security review expects to see at the API boundary. HTTP API is the right choice for lower-sensitivity internal APIs where the missing governance features are provided by IAM policies and the downstream service.

VPC private integrations

The most consequential network-level decision for a bank deployment is whether the API Gateway integrates with backend services through the public internet or through a VPC link. The default is the public internet — your Lambda functions or HTTP endpoints are called from the managed API Gateway fleet over HTTPS. For internal-only backends, this is unacceptable: the data plane traverses AWS infrastructure that is not inside your VPC security boundary.

VPC links solve this. A VPC Link is an elastic network interface injected into your VPC; API Gateway reaches your backend through it without the traffic leaving the AWS private network. There are two VPC link types:

• VPC Link for REST API — targets a Network Load Balancer inside your VPC. The NLB terminates at your private ALB or directly at your ECS / EKS service target groups.
• VPC Link for HTTP API — supports ALB, NLB, and AWS Cloud Map service discovery targets directly.

# CloudFormation: VPC Link for REST API → internal NLB
Resources:

  PaymentsNLB:
    Type: AWS::ElasticLoadBalancingV2::LoadBalancer
    Properties:
      Type: network
      Scheme: internal
      Subnets:
        - !Ref PrivateSubnetA
        - !Ref PrivateSubnetB

  ApiGwVpcLink:
    Type: AWS::ApiGateway::VpcLink
    Properties:
      Name: bank-payments-vpclink
      TargetArns:
        - !GetAtt PaymentsNLB.LoadBalancerArn

  PaymentsApi:
    Type: AWS::ApiGateway::RestApi
    Properties:
      Name: payments-api
      EndpointConfiguration:
        Types: [ REGIONAL ]     # PRIVATE if this endpoint must not be internet-routable

  PaymentsIntegration:
    Type: AWS::ApiGateway::Method
    Properties:
      Integration:
        Type: HTTP_PROXY
        Uri: !Sub "http://${PaymentsNLB.DNSName}/v1/{proxy}"
        ConnectionType: VPC_LINK
        ConnectionId: !Ref ApiGwVpcLink
        TimeoutInMillis: 29000   # max for REST API; must be < 29s

Two topology decisions embedded in this snippet that matter for a regulated environment:

• EndpointConfiguration: REGIONAL vs PRIVATE — a private endpoint is accessible only from within the VPC via an Interface VPC Endpoint (PrivateLink). No request reaches it from the internet. This is the correct choice for internal APIs consumed by your core banking middleware. A regional endpoint is internet-accessible but WAF-protected — correct for external partner APIs.
• TimeoutInMillis: 29000 — API Gateway hard-limits integration timeout at 29 seconds. Any synchronous backend call that takes longer will be cut off with a 504, even if the backend eventually responds. Legacy core banking systems with slow SQL calls regularly exceed this. Design your adapter layer to return a correlation ID and use a polling or callback pattern for long-running operations.

WAF coupling

AWS WAF v2 is the first line of defence for any internet-facing API Gateway endpoint. It evaluates each request before API Gateway processes it — blocking at the WAF level costs nothing in API Gateway invocations. The challenge is configuration: WAF ships with managed rule groups that are opinionated and will generate false positives against financial API payloads if tuned carelessly.

# Terraform: WAF WebACL for API Gateway REST endpoint
resource "aws_wafv2_web_acl" "api_gw_acl" {
  name  = "bank-apigw-waf"
  scope = "REGIONAL"    # CLOUDFRONT for edge-optimised endpoints

  default_action { allow {} }

  rule {
    name     = "AWSManagedRulesCommonRuleSet"
    priority = 1
    override_action { none {} }  # enforce; change to count{} when tuning
    statement {
      managed_rule_group_statement {
        vendor_name = "AWS"
        name        = "AWSManagedRulesCommonRuleSet"
        # SizeRestrictions_BODY blocks payloads > 8KB; ISO 20022 pain.001 exceeds this
        excluded_rule { name = "SizeRestrictions_BODY" }
      }
    }
    visibility_config {
      cloudwatch_metrics_enabled = true
      metric_name                = "CommonRuleSet"
      sampled_requests_enabled   = true
    }
  }

  rule {
    name     = "AWSManagedRulesKnownBadInputsRuleSet"
    priority = 2
    override_action { none {} }
    statement {
      managed_rule_group_statement {
        vendor_name = "AWS"
        name        = "AWSManagedRulesKnownBadInputsRuleSet"
      }
    }
    visibility_config {
      cloudwatch_metrics_enabled = true
      metric_name                = "KnownBadInputs"
      sampled_requests_enabled   = true
    }
  }

  rule {
    name     = "PartnerIPAllowlist"
    priority = 0             # evaluate before managed rules
    action   { allow {} }    # explicit allow skips remaining rules
    statement {
      ip_set_reference_statement {
        arn = aws_wafv2_ip_set.partner_cidrs.arn
      }
    }
    visibility_config {
      cloudwatch_metrics_enabled = true
      metric_name                = "PartnerAllowlist"
      sampled_requests_enabled   = false
    }
  }
}

WAF tuning is an ongoing activity, not a one-time configuration. The correct procedure for introducing a new managed rule group is:

1. Set override_action: count — the rule evaluates but does not block.
2. Run for 7 days under production-representative traffic.
3. Review sampled blocked requests in the WAF console for false positives.
4. Add exclusions for legitimate patterns, then switch to override_action: none (enforce).

Partners calling Open Banking endpoints are particularly sensitive to WAF false positives. A blocked request at the WAF level returns a 403 that API Gateway never sees — it will not appear in API Gateway access logs, only in WAF logs. Ensure WAF logs are flowing to CloudWatch Logs or S3 before going live.

Custom authorisers

API Gateway offers three authoriser types: Lambda authoriser (TOKEN or REQUEST), JWT authoriser (HTTP API only), and IAM authoriser. For a financial-services regulated endpoint the choice is almost always a Lambda TOKEN authoriser for REST API, because it gives you full control over the token validation logic — including introspection against a Keycloak or ADFS IdP, FAPI 2.0 certificate-bound token checks, and custom claim mapping to API Gateway context variables.

import os, json, boto3, hashlib
import urllib.request, urllib.parse

_sm = boto3.client("secretsmanager")
_cache = {}  # in-memory introspection cache (valid for Lambda warm lifecycle only)

def handler(event, context):
    token = event["authorizationToken"].removeprefix("Bearer ")
    method_arn = event["methodArn"]

    # FAPI 2.0: certificate-bound token check (cnf.x5t#S256 claim)
    client_cert_dn = event.get("requestContext", {}).get("identity", {}).get("clientCert", {}).get("subjectDN")

    # Cache key: SHA256 of raw token (never cache the token itself)
    cache_key = hashlib.sha256(token.encode()).hexdigest()[:16]
    if cache_key in _cache:
        return _cache[cache_key]

    claims = _introspect(token)
    if not claims or not claims.get("active"):
        raise Exception("Unauthorized")  # API Gateway interprets this as 401

    # Verify cert binding (RFC 8705 §3.1) when mTLS is enabled on the API
    if client_cert_dn and claims.get("cnf"):
        _verify_cert_binding(client_cert_dn, claims["cnf"])

    policy = _build_policy(claims["sub"], "Allow", method_arn, claims)
    _cache[cache_key] = policy
    return policy

def _build_policy(principal, effect, arn, claims):
    # Wildcard ARN: policy cached by API Gateway is reused across methods in same stage
    arn_parts = arn.split(":")
    arn_wildcard = ":".join(arn_parts[:6]) + ":*/*"
    return {
        "principalId": principal,
        "policyDocument": {
            "Version": "2012-10-17",
            "Statement": [{"Effect": effect, "Action": "execute-api:Invoke", "Resource": arn_wildcard}]
        },
        "context": {
            "sub":   claims.get("sub", ""),
            "scope": claims.get("scope", ""),
            "acr":   claims.get("acr", ""),
        },
    }

The context map returned by the authoriser is available in API Gateway mapping templates and access log format strings as $context.authorizer.sub, $context.authorizer.scope, etc. This is how you pass validated claims downstream to the backend without exposing the raw token.

mTLS configuration

AWS API Gateway supports mutual TLS for REST API and HTTP API regional and private endpoints. The configuration is different from Kong: you provide a truststore (a PEM bundle of trusted CA certificates) stored in S3, referenced in the API Gateway configuration. API Gateway evaluates the client certificate against the truststore on every TLS handshake and rejects the connection if the certificate is not signed by a trusted CA.

# Terraform: mutual TLS on API Gateway custom domain
resource "aws_api_gateway_domain_name" "ob_partner" {
  domain_name              = "api.acme-bank.com"
  regional_certificate_arn = aws_acm_certificate.api_cert.arn
  security_policy          = "TLS_1_2"   # SAMA CSF requires TLS 1.2 minimum

  mutual_tls_authentication {
    # S3 object containing PEM bundle of trusted partner CA certificates
    truststore_uri     = "s3://acme-bank-apigw-config/partner-ca-bundle.pem"
    truststore_version = aws_s3_object.partner_ca_bundle.version_id
  }

  endpoint_configuration {
    types = ["REGIONAL"]
  }
}

# Versioned S3 object for the truststore — rotation = upload new version and update version_id
resource "aws_s3_object" "partner_ca_bundle" {
  bucket = "acme-bank-apigw-config"
  key    = "partner-ca-bundle.pem"
  source = "./pki/partner-ca-bundle.pem"
  etag   = filemd5("./pki/partner-ca-bundle.pem")
}

There are two operational gaps in the AWS mTLS model compared to Kong. First, when a partner certificate is rejected at the TLS layer, the response is a TLS alert, not an HTTP 401 — it is invisible in API Gateway access logs and in the Lambda authoriser. You must enable WAF logging (which captures the TLS handshake failure) or CloudTrail to detect rejected client certificates. Second, there is no built-in certificate expiry monitoring in API Gateway. Build a Lambda function that periodically parses the truststore PEM bundle, extracts NotAfter fields, and publishes a CloudWatch metric that alarms 60 days before expiry.

Throttling & usage plans

API Gateway throttling operates at two levels: the account-level default (10,000 requests/second, 5,000 burst by default in the me-south-1 Bahrain region) and the usage-plan level (per API key, per stage, per method). Usage plans are the mechanism for encoding partner quotas.

1. Create a usage plan per partner tier

   Create separate usage plans for each commercial tier: standard (1,000 req/day, 10 req/sec), premium (100,000 req/day, 50 req/sec), bulk (1,000,000 req/day, 100 req/sec). Usage plans are not per-partner — they are per tier. Multiple partners share a plan; their individual quota consumption is tracked by their API key.

2. Generate and issue API keys at partner onboarding

   Create one API key per partner per environment (not one key shared across environments). Associate the key with the appropriate usage plan and the target API stage. Store the key in Secrets Manager and provide it to the partner via a secure channel — never by email.

3. Configure per-method throttling overrides

   Payment initiation endpoints (POST /payments) deserve lower burst limits than account inquiry (GET /accounts). Use per-method stage-level throttle overrides to enforce this independently of the usage plan limits.

4. Enable usage plan quota reset and monitor

   Quotas reset at the beginning of each calendar day (UTC) by default. If a partner’s quota resets at midnight Riyadh time (UTC+3), set the quota reset to 21:00 UTC. CloudWatch metric Count filtered by ApiKeyId gives you per-partner request counts for quota audit.

5. Export usage data for billing and dispute resolution

   The GetUsage API returns per-API-key usage for a date range. Automate a daily export to S3 in Parquet format; this is the durable audit record that answers “how many requests did partner X make on date Y” in a dispute or SAMA audit.

Request/response transformations

API Gateway REST API uses Apache Velocity Template Language (VTL) for request and response mapping templates. VTL is powerful but idiosyncratic — it is the most common source of subtle bugs in an API Gateway integration. HTTP API uses a simpler payload format version 2.0 with limited transformation support.

The use cases where VTL earns its keep in a bank environment:

• Extracting a correlation ID from an incoming ISO 20022 message and injecting it as a request header (X-Correlation-ID) for distributed tracing.
• Mapping a legacy SOAP response from an IBM MQ-backed service into a JSON structure expected by a modern mobile client — avoiding a Lambda proxy layer purely for shape translation.
• Normalising currency codes: incoming SAR → downstream 682 (ISO 4217 numeric) expected by the core banking system.

VTL templates are part of the API definition, tested in the API Gateway console (Test Invoke) or via the aws apigateway test-invoke-method CLI. The absence of unit tests for VTL is a common gap — treat templates as code, store them in version control, and test them in a dev stage before deploying to production.

Observability & audit logging

API Gateway provides three observability primitives: CloudWatch Metrics (auto-enabled), CloudWatch Logs access logging (opt-in, requires a CloudWatch Logs role ARN on the account), and AWS X-Ray distributed tracing (opt-in per stage).

The access log format is configurable via a JSON template. For SAMA compliance, the minimum fields are:

{
  "requestId":       "$context.requestId",
  "ip":              "$context.identity.sourceIp",
  "caller":          "$context.identity.caller",
  "user":            "$context.identity.user",
  "apiKey":          "$context.identity.apiKey",
  "clientCertDN":    "$context.identity.clientCert.subjectDN",
  "requestTime":     "$context.requestTime",
  "httpMethod":      "$context.httpMethod",
  "resourcePath":    "$context.resourcePath",
  "status":          "$context.status",
  "protocol":        "$context.protocol",
  "responseLatency": "$context.responseLatency",
  "integrationLatency": "$context.integrationLatency",
  "authoriserSub":   "$context.authorizer.sub",
  "authoriserScope": "$context.authorizer.scope",
  "wafResponse":     "$context.wafResponseCode",
  "errorMessage":    "$context.error.message"
}

Forward these logs to your SIEM using a CloudWatch Logs subscription filter pointing to a Kinesis Data Firehose delivery stream, which lands them in S3 (Parquet with Glue catalog) or directly in your SIEM ingest endpoint. The clientCertDN field is only populated when mTLS is enabled on the custom domain; for API-key-authenticated traffic it will be empty. The authoriserSub field relies on the Lambda authoriser returning it in the context map — as shown in the code block above.

Production topology

A production API Gateway topology for a regulated KSA bank uses the Bahrain region (me-south-1) as the primary, with a secondary in UAE (me-central-1) for disaster recovery. Route 53 latency routing or health-check failover handles the DNS tier.

Infrastructure-as-code discipline is non-negotiable here. The API definition, WAF rule set, Lambda authoriser code, VPC link configuration, and CloudWatch log format must all be in Terraform or CloudFormation and deployed through a CI/CD pipeline — not hand-configured in the console. A SAMA audit will ask for change history on the security configuration; a Git-controlled IaC repository provides that history. Console changes do not.

Common pitfalls

Comparison with Kong & IBM API Connect

AWS API Gateway is a managed service that eliminates the operational overhead of running gateway infrastructure. Kong and IBM API Connect are self-managed (or vendor-SaaS) products that give you more control over the feature set and the deployment topology. Neither model is universally better; the choice depends on which dimension of control matters most.

Decision framework

The question “should we use AWS API Gateway?” decomposes into four sub-questions that each have a clear answer for most regulated banks:

• Is the workload on AWS? AWS API Gateway is the lowest-friction choice when your backend services are on ECS, EKS, or Lambda. The VPC Link integration is tight. If your backend is on-prem or on another cloud, the VPC Link requires a VPN or Direct Connect to close the network path, and the latency overhead may be significant.
• Do you need a developer portal and API catalogue? AWS API Gateway does not include a developer portal. Consumers discover APIs through the developer team, not through a managed catalogue. If you have external third-party developers onboarding to your APIs, you need to build or buy a portal separately (AWS does not have one; consider a custom one via Backstage or a commercial add-on). Kong Enterprise includes a portal; IBM API Connect includes the most mature one in the market.
• Is vendor lock-in a constraint? SAMA’s IT Governance Framework explicitly calls out cloud provider lock-in as a risk to manage. AWS API Gateway’s VTL templates and authoriser model are not portable. Kong’s declarative config can be migrated to a self-hosted cluster. If your institution’s cloud strategy requires gateway portability, Kong with a cloud-agnostic Kubernetes platform is the lower lock-in option.
• Who will operate it? AWS API Gateway requires almost no operational staffing for the gateway itself, but it requires significant IaC and security-policy expertise to configure correctly. Kong requires operational staffing for the gateway, but the configuration is more inspectable and debuggable. The right answer depends on the skill profile of the platform team, not on the product feature list.

For a greenfield API programme on AWS — cloud-native backend, small team, no existing gateway investment — AWS API Gateway REST API with WAF and a Lambda authoriser is the correct starting point. Add Kong later if the consumer management and developer portal requirements outgrow what API Gateway provides natively. For a migration from IBM API Connect in a hybrid/on-prem environment, Kong is the closer semantic fit and the lower lock-in choice.