Introduction

Integrating API Gateway with S3 through AWS CDK is a common way to expose object download or upload endpoints without running an always-on backend service. This pattern is fast and cost-effective for simple file APIs, but security and mapping details matter. A correct implementation sets explicit IAM permissions, request mapping, and CORS behavior from the start.

Choose an Integration Pattern First

There are two main patterns:

• Direct service integration, where API Gateway calls S3 operations directly.
• Lambda proxy, where Lambda applies custom logic and then talks to S3.

Direct integration is ideal for simple read or write routes. Lambda proxy is better when you need complex validation, custom auth checks, or multi-step business logic.

For this article, we focus on direct integration with CDK.

CDK Stack with S3 and API Gateway

The following TypeScript stack creates:

• A private S3 bucket.
• A role that API Gateway can assume.
• A REST route for object reads by key.

1import * as cdk from "aws-cdk-lib";
2import * as apigw from "aws-cdk-lib/aws-apigateway";
3import * as iam from "aws-cdk-lib/aws-iam";
4import * as s3 from "aws-cdk-lib/aws-s3";
5import { Construct } from "constructs";
6
7export class ApiS3Stack extends cdk.Stack {
8  constructor(scope: Construct, id: string, props?: cdk.StackProps) {
9    super(scope, id, props);
10
11    const bucket = new s3.Bucket(this, "DocsBucket", {
12      blockPublicAccess: s3.BlockPublicAccess.BLOCK_ALL,
13      encryption: s3.BucketEncryption.S3_MANAGED,
14    });
15
16    const apiRole = new iam.Role(this, "ApiGatewayS3Role", {
17      assumedBy: new iam.ServicePrincipal("apigateway.amazonaws.com"),
18    });
19
20    bucket.grantRead(apiRole);
21
22    const api = new apigw.RestApi(this, "DocsApi", {
23      restApiName: "docs-api",
24    });
25
26    const files = api.root.addResource("files");
27    const keyRes = files.addResource("{key}");
28
29    const s3GetIntegration = new apigw.AwsIntegration({
30      service: "s3",
31      integrationHttpMethod: "GET",
32      path: `${bucket.bucketName}/{key}`,
33      options: {
34        credentialsRole: apiRole,
35        requestParameters: {
36          "integration.request.path.key": "method.request.path.key",
37        },
38        integrationResponses: [
39          { statusCode: "200" },
40          { statusCode: "404" },
41        ],
42      },
43    });
44
45    keyRes.addMethod("GET", s3GetIntegration, {
46      requestParameters: {
47        "method.request.path.key": true,
48      },
49      methodResponses: [
50        { statusCode: "200" },
51        { statusCode: "404" },
52      ],
53    });
54  }
55}

This gives a minimal read endpoint while keeping the bucket private.

Add Upload Support Safely

For uploads, prefer constrained write access and predictable key prefixes.

bucket.grantPut(apiRole, "uploads/*");

You can define a separate PUT method and map request path key similarly. Restricting writes to uploads prevents accidental overwrite of system files.

For browser uploads, many teams choose pre-signed URLs from a small auth service instead of direct unauthenticated API Gateway writes.

CORS and Response Headers

If clients call from browser apps, configure CORS on the API resources and confirm S3 response headers are forwarded correctly.

CDK example for preflight on the files resource:

1files.addCorsPreflight({
2  allowOrigins: ["https://app.example.com"],
3  allowMethods: ["GET", "PUT", "OPTIONS"],
4  allowHeaders: ["Content-Type", "Authorization"],
5});

Without this, browser requests may fail even when backend integration is correct.

Deploy and Test

After deploy:

cdk deploy

Then test the route:

curl -i "https://<api-id>.execute-api.<region>.amazonaws.com/prod/files/example.txt"

Verify:

• Existing object returns 200.
• Missing object returns expected 404 mapping.
• IAM role has only required S3 permissions.

Security and Operations Checklist

For production readiness:

• Keep bucket public access blocked.
• Scope API Gateway role to exact S3 actions and prefixes.
• Add throttling and usage plans where needed.
• Log API access and inspect error metrics in CloudWatch.

If endpoint is internet-facing and high traffic, consider WAF protections and request-size controls.

Common Pitfalls

• Granting broad S3 permissions to API role. Fix by limiting actions and key prefixes.
• Forgetting path parameter mapping from method to integration request. Fix by configuring both request parameter maps.
• Mixing direct integration and business logic-heavy workflows. Fix by moving complex logic to Lambda.
• Skipping CORS configuration for browser clients. Fix by defining preflight rules explicitly.
• Leaving bucket public while also routing through API. Fix by keeping one clear access path and enforcing private bucket policy.

Summary

• CDK can define a secure API Gateway to S3 integration with little code.
• Direct service integration is best for straightforward file APIs.
• Correct IAM scoping and request mapping are the core implementation details.
• CORS and response mapping determine whether browser clients work reliably.
• Start with minimal access, then expand capabilities only when required.