Introduction

This error usually means API Gateway was given an IAM role ARN for the integration, but the role either does not trust API Gateway or does not have the right permissions once assumed. In an S3 proxy setup, both pieces matter: API Gateway must be allowed to assume the role, and the assumed role must be allowed to access the target bucket objects.

What API Gateway Is Trying to Do

For an AWS service integration to S3, API Gateway can use a credentials role. At runtime it tries to assume that role and then call S3 on your behalf.

If the assume-role step fails, you get the error before S3 permissions are even evaluated.

Fix the Trust Relationship First

The IAM role used by the integration must trust the API Gateway service principal.

1{
2  "Version": "2012-10-17",
3  "Statement": [
4    {
5      "Effect": "Allow",
6      "Principal": {
7        "Service": "apigateway.amazonaws.com"
8      },
9      "Action": "sts:AssumeRole"
10    }
11  ]
12}

If that trust policy is missing or wrong, API Gateway cannot assume the role no matter what S3 permissions you attach later.

Then Attach the S3 Permissions

Once the trust policy is correct, the same role still needs permission to perform the actual S3 action required by the integration.

1{
2  "Version": "2012-10-17",
3  "Statement": [
4    {
5      "Effect": "Allow",
6      "Action": [
7        "s3:GetObject"
8      ],
9      "Resource": "arn:aws:s3:::my-bucket/*"
10    }
11  ]
12}

Change the action and resource to match your use case, such as PutObject for uploads.

Verify the Role ARN in the Integration

A perfectly configured role still will not help if API Gateway points to the wrong ARN. Double-check the credentials field in the integration settings or IaC definition.

For example, in CloudFormation or OpenAPI-backed definitions, make sure the integration credentials value is the exact role ARN you intended.

Bucket Policy Can Still Matter

If the bucket policy is restrictive, the assumed role may still be blocked even after a successful assume-role step. That produces a different kind of failure, but it is worth checking if the trust relationship looks correct and the error evolves into an S3 access problem.

In other words:

• trust policy controls whether API Gateway can assume the role
• IAM permissions and bucket policy control what the assumed role can do in S3

Redeploy After Changes

API Gateway deployments often require an explicit redeploy before configuration changes take effect. If you fix the IAM role and still see the old error immediately, confirm that the API stage was redeployed.

This is a common source of confusion during iterative debugging.

Common Pitfalls

• Adding S3 permissions without fixing the trust relationship first does not solve the assume-role failure.
• Using the wrong service principal in the trust policy prevents API Gateway from assuming the role.
• Pointing the integration at the wrong role ARN makes the configuration look correct in IAM but wrong in API Gateway.
• Forgetting bucket-policy restrictions can lead to a second permission problem after the first one is fixed.
• Not redeploying the API after integration changes can make debugging feel inconsistent.

Summary

• This error usually starts with a bad or missing trust relationship on the IAM role.
• The role must trust apigateway.amazonaws.com for sts:AssumeRole.
• The same role also needs the right S3 permissions once assumed.
• Verify the exact role ARN configured in the integration.
• Redeploy the API after changes so you are testing the current configuration, not an old deployment.