AWS API Gateway skill for Codex

Done well means: the API type matches the features actually needed, every route has an explicit authorizer (or is deliberately public), throttling protects the backend, structured access logs identify every failed request, and the default execute-api endpoint is not a back door around the custom domain and WAF.

Before changing anything

1. Read AGENTS.md and the IaC (SAM, CDK, Terraform, OpenAPI file). Identify the API type: AWS::ApiGatewayV2::Api / AWS::Serverless::HttpApi is an HTTP API; AWS::ApiGateway::RestApi / AWS::Serverless::Api is a REST API.
2. Inspect live config when credentials and network are available:

aws apigatewayv2 get-apis --query 'Items[].[Name,ApiId,ProtocolType,DisableExecuteApiEndpoint]'
aws apigatewayv2 get-routes --api-id $API --query 'Items[].[RouteKey,AuthorizationType,AuthorizerId]' --output table
aws apigateway get-rest-apis --query 'items[].[name,id,endpointConfiguration.types[0]]'
aws apigateway get-stage --rest-api-id $API --stage-name prod --query '{throttle:methodSettings,logs:accessLogSettings,waf:webAclArn}'

HTTP API or REST API

Default to HTTP API: lower price per request, lower latency, simpler config. Choose REST API only when you need one of its features:

Need	HTTP API	REST API
JWT / OIDC authorizer (Cognito, Auth0, Entra ID)	Native	Cognito authorizer or Lambda authorizer
Lambda authorizer, IAM auth	Yes	Yes
API keys and usage plans (per-customer quotas)	No	Yes
AWS WAF directly on the API	No (put CloudFront plus WAF in front)	Yes
Response caching	No	Yes
Request validation, VTL mapping templates	No	Yes
Private endpoint (VPC-only API)	No	Yes
Resource policies (IP/VPC/account restrictions)	No	Yes
Canary stage deployments, X-Ray tracing	No	Yes
Max integration timeout	30 s	29 s default, raisable for regional and private APIs

Both: 10 MB payload limit, Lambda and HTTP proxy integrations, custom domains, WebSocket support exists as a separate API type.

Lambda proxy integrations

HTTP APIs should use payload format 2.0; REST APIs use the 1.0 shape.

def handler(event, context):
    method = event["requestContext"]["http"]["method"]     # 2.0
    path = event["rawPath"]
    claims = event["requestContext"].get("authorizer", {}).get("jwt", {}).get("claims", {})
    return {
        "statusCode": 200,
        "headers": {"content-type": "application/json"},
        "body": json.dumps({"user": claims.get("sub")}),
    }

• body must be a string. Returning a dict body, a missing statusCode, or an uncaught exception yields 502 (Malformed Lambda proxy response on REST, Internal Server Error on HTTP API).
• Binary responses need isBase64Encoded: true and, on REST APIs, binary media types configured.
• Keep the Lambda timeout below the API’s integration timeout, and the downstream timeouts below the Lambda timeout, so errors are explicit rather than 504s.

Authorization

Caller	Use
Browser or mobile app with an identity provider	JWT authorizer (HTTP API) with issuer and audience; route-level scopes
Service-to-service inside AWS	IAM auth (SigV4) with least-privilege execute-api:Invoke on route ARNs
Custom tokens, API keys you validate yourself, multi-tenant rules	Lambda authorizer
Partners with quotas	REST API usage plans with API keys, plus a real authorizer (API keys alone are not authentication)

JWT authorizer (SAM, HTTP API):

OrdersApi:
  Type: AWS::Serverless::HttpApi
  Properties:
    Auth:
      DefaultAuthorizer: Cognito
      Authorizers:
        Cognito:
          IdentitySource: $request.header.Authorization
          JwtConfiguration:
            issuer: !Sub https://cognito-idp.${AWS::Region}.amazonaws.com/${UserPool}
            audience: [!Ref UserPoolClient]

The authorizer checks aud, or client_id for Cognito access tokens. Use AuthorizationScopes per route for scope checks. Setting a default authorizer and explicitly opting public routes out (Authorizer: NONE) is safer than the reverse.

Lambda authorizer caching trap (REST, TOKEN/REQUEST type): the policy returned is cached per identity for the TTL (300 s default) and reused for every method. If the policy only allows the methodArn of the first call, the next route returns 403. Return a policy covering the routes the identity may call (e.g. arn:aws:execute-api:region:acct:api/stage/*) or include the route in the identity source. For HTTP APIs, prefer simple responses ({"isAuthorized": true, "context": {...}}).

CORS

• HTTP API: configure CorsConfiguration on the API (allowed origins, methods, headers, AllowCredentials). API Gateway answers preflight; do not also add OPTIONS routes that hit Lambda. Credentials cannot be combined with origin *.
• REST API with Lambda proxy: API Gateway CORS settings only cover the OPTIONS mock; your Lambda must return Access-Control-Allow-Origin on every response, including errors. Also add CORS headers to gateway responses (DEFAULT_4XX, DEFAULT_5XX) so auth failures are readable by the browser instead of looking like CORS errors.

Throttling and protection

• Account-level default is 10,000 requests per second with a 5,000 burst per region, shared by all APIs. One noisy API can starve the others; set stage or route limits.
• HTTP API: route-level throttling in stage RouteSettings. REST API: method settings per stage (*/* for all) and usage plans per API key.
• Throttled requests return 429; clients should back off with jitter.
• Public REST APIs: attach AWS WAF with rate-based rules and managed rule groups. HTTP APIs: front them with CloudFront plus WAF, and disable the default endpoint.

Custom domains and endpoints

• Regional custom domain with an ACM certificate in the same region; edge-optimized REST APIs need the certificate in us-east-1.
• Map base paths (/v1, /v2) to stages or APIs.
• Set DisableExecuteApiEndpoint: true once the custom domain works, so clients cannot bypass the domain, CloudFront and WAF.

Logging

Enable access logs in JSON on every stage; execution logs on REST only when debugging (they can contain request data).

{"requestId":"$context.requestId","ip":"$context.identity.sourceIp","method":"$context.httpMethod",
 "path":"$context.path","status":"$context.status","latency":"$context.responseLatency",
 "integrationStatus":"$context.integrationStatus","integrationError":"$context.integrationErrorMessage",
 "authError":"$context.authorizer.error"}

Debugging table

Symptom	Cause
REST 403 Missing Authentication Token	Route or stage does not exist (wrong path, missing stage prefix, not deployed), not an auth problem
REST change not visible	REST APIs need a new deployment to the stage: aws apigateway create-deployment --rest-api-id $API --stage-name prod
401 on HTTP API with valid token	Wrong issuer (trailing slash), audience mismatch, ID token vs access token
403 after first successful call	Lambda authorizer cached a narrow policy
502	Malformed Lambda response or Lambda error; check integrationError in access logs
504	Integration timeout; backend slower than 29-30 s or stuck on network
Browser shows CORS error on 401/500	Missing CORS headers on error responses or gateway responses

Deploying to a production stage or removing routes is outward-facing: confirm with the user first.

Verification

curl -i https://api.acme.com/v1/orders                                  # 401 without token
curl -i -H "Authorization: Bearer $TOKEN" https://api.acme.com/v1/orders # 200
curl -i https://$API.execute-api.eu-west-1.amazonaws.com/orders         # fails once disabled
curl -i -X OPTIONS -H "Origin: https://app.acme.com" \
  -H "Access-Control-Request-Method: POST" https://api.acme.com/v1/orders

Then confirm access log lines show status, latency and authorizer errors for each request.