aws s3api put-bucket-policy
aws s3api put-bucket-policy --bucket my-bucket --policy file://policy.json attaches a JSON resource policy to a bucket, replacing any policy already there. Read the current one first with get-bucket-policy, keep bucket-level and object-level resources straight (arn:aws:s3:::my-bucket vs my-bucket/*), and expect Block Public Access to reject policies that grant public access.
What the command does
A bucket has at most one policy document. This command overwrites it entirely; there is no "add a statement" operation, so to change one statement you fetch the policy, edit it and put the whole thing back.
Bucket policies are how you grant access to other accounts, AWS services such as CloudFront or CloudTrail, or deny requests that do not meet conditions like TLS or a VPC endpoint. Requests from your own account's IAM principals can be allowed by either the IAM policy or the bucket policy; an explicit Deny in either wins.
Syntax
aws s3api put-bucket-policy --bucket my-bucket --policy file://policy.json
# read it back, pretty-printed
aws s3api get-bucket-policy --bucket my-bucket --query Policy --output text | python3 -m json.tool
Always use file://. Inlining a policy on the command line invites quoting errors that turn into MalformedPolicy.
Worked examples
Deny any request not using TLS (a common audit finding):
{
"Version": "2012-10-17",
"Statement": [{
"Sid": "DenyInsecureTransport",
"Effect": "Deny",
"Principal": "*",
"Action": "s3:*",
"Resource": ["arn:aws:s3:::my-bucket", "arn:aws:s3:::my-bucket/*"],
"Condition": { "Bool": { "aws:SecureTransport": "false" } }
}]
}
Let one CloudFront distribution read objects through Origin Access Control:
{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Principal": { "Service": "cloudfront.amazonaws.com" },
"Action": "s3:GetObject",
"Resource": "arn:aws:s3:::my-bucket/*",
"Condition": { "StringEquals": {
"AWS:SourceArn": "arn:aws:cloudfront::123456789012:distribution/E1ABCDEF234567"
} }
}]
}
Give another account read access to a prefix, which needs both list and get:
{
"Version": "2012-10-17",
"Statement": [
{ "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::210987654321:root" },
"Action": "s3:ListBucket", "Resource": "arn:aws:s3:::my-bucket",
"Condition": { "StringLike": { "s3:prefix": "shared/*" } } },
{ "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::210987654321:root" },
"Action": "s3:GetObject", "Resource": "arn:aws:s3:::my-bucket/shared/*" }
]
}
The other account still has to grant its own users permission in IAM.
Check whether the result makes the bucket public:
aws s3api get-bucket-policy-status --bucket my-bucketErrors
| Error | Cause |
|---|---|
MalformedPolicy: Policy has invalid resource | The resource names another bucket, or uses an object action on the bucket ARN (or the reverse). |
MalformedPolicy: Invalid principal | The account or role ARN does not exist, or a deleted role is referenced. |
AccessDenied on put | Block Public Access BlockPublicPolicy is on and the policy grants public access, or you lack s3:PutBucketPolicy. |
Gotchas
- Locking yourself out. A broad
Deny(for example on a condition your own role does not meet) can block everyone, including admins. The account root user can still delete the policy withaws s3api delete-bucket-policy --bucket my-bucket. - Size limit. Bucket policies are limited to 20 KB; long lists of principals or IPs belong in IAM or a prefix-list-based design.
- KMS is separate. Granting another account access to SSE-KMS objects also needs the KMS key policy to allow them.
- Infrastructure as code wins. If CloudFormation or Terraform manages the bucket, a manual put will be overwritten on the next deploy.
Questions
Does put-bucket-policy replace the existing policy?
Yes, completely. Download the current policy with get-bucket-policy, merge your change, and put the full document back.
Why does put-bucket-policy return Access Denied?
Usually Block Public Access is rejecting a policy that grants public access, or your identity lacks s3:PutBucketPolicy. Check get-public-access-block on the bucket and account.
How do I remove a bucket policy?
Run aws s3api delete-bucket-policy --bucket my-bucket. The root user of the bucket owner account can always do this.
Bucket policy changes are worth reviewing carefully rather than rushing from a small screen. CloudConsole, a phone app for AWS, is built with production guardrails and to surface the alarms and resources around a change like this.
About the app → · Download on the App Store