Docs

Amazon S3

13 min readUpdated November 9, 2026

Amazon S3 is object storage from Amazon Web Services (AWS). WP Media Cloud uploads your Media Library to one S3 bucket. It then serves every file from a CDN in front of the bucket, ideally Amazon CloudFront, or from the bucket’s own address.

This guide uses an IAM user whose keys can only touch your one bucket. The bucket stays private, and CloudFront is the only thing allowed to read it.

How access works#

What it isRequired?
IAM user with access keysAn Access Key ID and Secret Access Key. The policy in Step 3 limits them to one bucket.Yes
Public address for your filesA CloudFront distribution (recommended) or a public bucket policyYes
CloudWatch read permissionLets the Dashboard show your bucket’s storage sizeNo, optional

WP Media Cloud uploads, reads, restores and deletes files with the bucket keys. Visitors never use those keys. They load files from CloudFront or from the bucket’s public address.

Before you start#

  • An AWS account you can sign in to with permission to create S3 buckets, IAM users and CloudFront distributions.
  • A bucket name without dots (periods). AWS warns that names with dots break HTTPS on the bucket’s own address. WP Media Cloud always uses HTTPS with S3.
  • Your own domain (optional). CloudFront gives you a free address such as d111111abcdef8.cloudfront.net. You can add your own domain later.

Step 1: Create a bucket#

  1. Open the S3 console.
  2. In the navigation bar, choose the Region where you want the bucket. You cannot change it later.
  3. In the left menu, choose General purpose buckets, then Create bucket.
  4. Enter a Bucket name, for example example-media. Use 3 to 63 lowercase letters, numbers and hyphens, starting and ending with a letter or number.
  5. Leave Object Ownership on Bucket owner enforced (default). This keeps ACLs disabled, which is what WP Media Cloud expects.
  6. Leave Block all public access turned on. You only change this if you choose Option B in Step 2.
  7. Leave Default encryption on Server-side encryption with Amazon S3 managed keys (SSE-S3). SSE-KMS needs extra KMS permissions for both the IAM user and CloudFront.
  8. Select Create bucket.

Write down the bucket name and the Region code, such as eu-west-1. You need both in Step 5.

Step 2: Give your files a public address#

New buckets are private, so visitors cannot load your images yet. Choose one of the two options below.

  1. Open the CloudFront console and select Create distribution.
  2. Enter a Distribution name, for example example.com media.
  3. Under plan selection, choose Single website or app, then select Next.
  4. Select Next again until you reach the origin settings.
  5. Set Origin type to Amazon S3.
  6. Under S3 origin, select Browse S3 and choose your bucket.
  7. Choose Use recommended origin settings. This sets up origin access control (OAC), so only this distribution can read the bucket.
  8. Select Next. Choose whether to turn on AWS WAF protections, then select Next.
  9. Select Create distribution. CloudFront adds the bucket policy that lets it read your files.
  10. Wait until Last modified changes from Deploying to a date. Then copy the domain name, which looks like d111111abcdef8.cloudfront.net.

The bucket stays private and Block Public Access stays on. WP Media Cloud stores every file with a one-year Cache-Control header, so CloudFront and browsers can keep files for a long time.

To use your own address, such as media.example.com, add it to the distribution as an alternate domain name with a certificate. Follow the CloudFront documentation for this. Then use that address as your CDN URL.

Option B: Public bucket, no CDN#

Use this only if you do not want a CDN. Anyone can read every file in the bucket.

  1. Open your bucket and go to the Permissions tab.
  2. Under Block public access (bucket settings), select Edit.
  3. Clear Block all public access, select Save changes and confirm.
  4. Under Bucket policy, select Edit and paste this policy. Replace example-media with your bucket name.
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "PublicReadGetObject",
      "Effect": "Allow",
      "Principal": "*",
      "Action": "s3:GetObject",
      "Resource": "arn:aws:s3:::example-media/*"
    }
  ]
}
  1. Select Save changes.

Files are then served from https://example-media.s3.eu-west-1.amazonaws.com, using your bucket name and Region.

Step 3: Create an IAM user limited to your bucket#

This user exists only for WP Media Cloud. It needs no console password.

  1. Open the IAM console and choose Users, then Create user.
  2. Enter a User name, for example wp-media-cloud-example-com.
  3. Leave Provide user access to the AWS Management Console unticked. Select Next.
  4. On Set permissions, choose Attach policies directly but do not tick any policy. Select Next, then Create user.
  5. Open the new user. On the Permissions tab, choose Add permissions, then Create inline policy.
  6. Choose the JSON editor and paste the policy below. Replace example-media with your bucket name.
  7. Select Next, name the policy, for example wp-media-cloud-example-media, and select Create policy.
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "MediaFilesInOneBucket",
      "Effect": "Allow",
      "Action": [
        "s3:PutObject",
        "s3:GetObject",
        "s3:DeleteObject",
        "s3:AbortMultipartUpload"
      ],
      "Resource": "arn:aws:s3:::example-media/*"
    }
  ]
}
Code
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "MediaFilesInOneBucket",
      "Effect": "Allow",
      "Action": [
        "s3:PutObject",
        "s3:GetObject",
        "s3:DeleteObject",
        "s3:AbortMultipartUpload"
      ],
      "Resource": "arn:aws:s3:::example-media/*"
    }
  ]
}

MediaFilesInOneBucket lets WP Media Cloud upload, read, restore and delete files in this bucket only. s3:PutObject also covers large files, which are sent in parts. s3:AbortMultipartUpload cleans up a large upload that fails halfway.

Optional: bucket list for the Load button#

You type the bucket name in the setup wizard, so this policy is enough. If you want the wizard’s Load button to list your buckets, add this statement to the same policy.

{
  "Sid": "WizardBucketList",
  "Effect": "Allow",
  "Action": "s3:ListAllMyBuckets",
  "Resource": "*"
}

AWS requires "Resource": "*" for this permission, so it cannot be limited to one bucket. It shows bucket names only. It cannot read, change or delete anything.

WP Media Cloud never lists the contents of your bucket, so neither statement includes s3:ListBucket.

Optional: storage size on the Dashboard#

To show your bucket’s size on the Dashboard, add this statement to the same policy. CloudWatch does not support limiting it to one bucket, so the resource must be *. It can only read metrics.

{
  "Sid": "DashboardStorageSize",
  "Effect": "Allow",
  "Action": "cloudwatch:GetMetricStatistics",
  "Resource": "*"
}

Step 4: Create the access keys#

  1. In the IAM console, open your user and go to the Security credentials tab.
  2. Under Access keys, select Create access key.
  3. Choose Other as the use case and select Next.
  4. Optionally add a description tag, such as example.com. Select Create access key.
  5. On Retrieve access key, select Show. Copy the Access key and Secret access key into a password manager, or select Download .csv file.

Copy the secret access key now. AWS shows it only once and cannot recover it. If you lose it, create a new access key and delete the old one.

Step 5: Connect WP Media Cloud#

Setup wizard Connect step for Amazon S3

In WordPress, open Media Cloud. The setup wizard opens on first use. Choose Amazon S3 and select Continue.

FieldWhat to enter
RegionYour bucket’s Region code from Step 1, for example eu-west-1. If you leave it empty, us-east-1 is used.
Access Key IDThe access key from Step 4, starting with AKIA
Secret Access KeyThe secret access key from Step 4
Bucket nameType your bucket name from Step 1, for example example-media. Load can fill a list to pick from, but only if you added the optional WizardBucketList statement.
CloudWatch StatsOptional. Tick Enable CloudWatch storage stats if you added the CloudWatch statement in Step 3.
CDN ConfigurationOption A: choose Custom CDN. Option B: choose Direct bucket URL, which serves files from your S3 bucket’s own address.
CDN URLShown for Custom CDN. Enter your CloudFront address with https://, for example https://d111111abcdef8.cloudfront.net, or your own domain.

You can also pick Bunny.net CDN, KeyCDN, EWWW Easy IO or CDN77 under CDN Configuration. These pull files over the public internet, so they need the public bucket from Option B. They also let the Dashboard show CDN bandwidth.

Select Continue, then Save & Go to Dashboard.

Check that it works#

The Amazon S3 wizard has no Test connection button. Upload a test instead:

  1. Upload an image in Media.
  2. In Media, then Library, switch to list view. The image row should show In cloud.
  3. Open the image. Its address should start with your CDN URL, and it should load.

If the row shows Offload failed, hover over it to read the error, then see Troubleshooting. Failed items are also listed in the Bulk Offload card on the Dashboard.

The Health page checks that your keys and bucket are saved and that the CDN URL responds. For Amazon S3 it does not upload a test file.

Changing your bucket or keys later#

Object Permissions card in Settings for Amazon S3

Go to Settings and select run the setup wizard. Your offloaded files, records and other settings are kept.

In WP Media Cloud 1.1.8 or newer, the wizard opens with your saved settings filled in. This includes the Region, bucket name, CDN choice and CDN URL. Saved keys show as Saved. Paste only the keys you are changing, and leave the others as they are.

Alternative: Connect with wp-config.php#

wp-config.php constants for Amazon S3 from the setup wizard

Instead of the wizard, you can define your settings in wp-config.php, above the line /* That's all, stop editing! */. Values set here override anything saved in the admin, which suits sites managed in version control.

Multisite: constants in wp-config.php apply to every subsite, so they point every subsite at the same bucket. That works when each subsite keeps its files in its own folder: also add define( 'WPMC_PATH_PREFIX', 'sites/%site_id%' );. Or set up each subsite in its own dashboard. See Custom path prefix.

// Required
define( 'WPMC_PROVIDER',       'aws' );
define( 'WPMC_AWS_REGION',     'eu-west-1' );
define( 'WPMC_AWS_ACCESS_KEY', 'your-access-key-id' );
define( 'WPMC_AWS_SECRET_KEY', 'your-secret-access-key' );
define( 'WPMC_AWS_BUCKET',     'example-media' );

// Optional: serve files through CloudFront or another CDN.
// Leave both out to serve files from the bucket's own address (Option B).
define( 'WPMC_AWS_CDN_TYPE',   'custom' );
define( 'WPMC_AWS_CDN_URL',    'https://d111111abcdef8.cloudfront.net' );

// Optional: storage size on the Dashboard (needs the CloudWatch statement).
define( 'WPMC_AWS_CLOUDWATCH', true );

// Optional: object ACL. Keep 'private' on buckets with ACLs disabled.
define( 'WPMC_AWS_ACL',        'private' );
Code
// Required
define( 'WPMC_PROVIDER',       'aws' );
define( 'WPMC_AWS_REGION',     'eu-west-1' );
define( 'WPMC_AWS_ACCESS_KEY', 'your-access-key-id' );
define( 'WPMC_AWS_SECRET_KEY', 'your-secret-access-key' );
define( 'WPMC_AWS_BUCKET',     'example-media' );

// Optional: serve files through CloudFront or another CDN.
// Leave both out to serve files from the bucket's own address (Option B).
define( 'WPMC_AWS_CDN_TYPE',   'custom' );
define( 'WPMC_AWS_CDN_URL',    'https://d111111abcdef8.cloudfront.net' );

// Optional: storage size on the Dashboard (needs the CloudWatch statement).
define( 'WPMC_AWS_CLOUDWATCH', true );

// Optional: object ACL. Keep 'private' on buckets with ACLs disabled.
define( 'WPMC_AWS_ACL',        'private' );

The first five lines are required. Set the Region even if it is us-east-1, because WP Media Cloud does not start offloading without it.

Then open Media Cloud. On the first wizard screen, select Configure via wp-config.php, then Done, constants added.

The Dashboard and the Health page read these constants too.

For other CDNs, the generator also prints optional constants such as WPMC_AWS_BUNNY_API_KEY, WPMC_AWS_PULL_ZONE_HOSTNAME, WPMC_AWS_KEYCDN_ZONE_URL, WPMC_AWS_EWWW_API_KEY and WPMC_AWS_CDN77_URL. WP Media Cloud reads every one of them.

After setup#

  • New uploads are offloaded automatically and served from your CDN URL.
  • Existing media is not moved until you start a bulk offload from the Dashboard with Offload All Media. On large libraries or multisite, wp wpmc offload (or wp wpmc offload --network) is faster.
  • Changing your CDN URL later, for example to your own domain: run the setup wizard again and enter the new CDN URL. Offloaded files use the new address straight away. Amazon S3 has no Update all media URLs button in Settings.
  • Dashboard stats: Storage Used needs CloudWatch Stats and the CloudWatch permission. AWS reports bucket size once a day, so the first figure can take a day. CDN bandwidth is shown only for Bunny.net CDN, KeyCDN, EWWW Easy IO and CDN77. CloudFront bandwidth is not shown.
  • WooCommerce secure downloads are available with Bunny.net and Cloudflare R2 only. With Amazon S3, the WooCommerce card says so, and downloadable product files use their normal CDN URL.
  • Object ACL: Settings, Object Permissions has an Object ACL option. Keep it on private. Buckets with ACLs disabled reject public-read.

Troubleshooting#

What you seeWhat it meansHow to fix it
Load shows an errorThe keys are wrong, or the policy has no s3:ListAllMyBuckets. The wizard shows the error below the field.Type the bucket name instead. If the keys are wrong, paste them again with no spaces at either end.
Offload failed: HTTP 403 InvalidAccessKeyIdThe Access Key ID does not exist. It may have a typo, or it was deleted.Copy the key again from IAM, or create a new access key.
Offload failed: HTTP 403 SignatureDoesNotMatchThe Secret Access Key is wrong.Paste it again. If you no longer have it, create a new access key.
Offload failed: HTTP 403 AccessDeniedThe IAM policy does not allow writing to this bucket.Check that the bucket name in arn:aws:s3:::example-media/* matches exactly. If the bucket uses SSE-KMS, switch it to SSE-S3 or add KMS permissions.
Offload failed: HTTP 301 PermanentRedirect or HTTP 400 AuthorizationHeaderMalformedThe Region does not match the bucket.Check the bucket’s AWS Region in the S3 bucket list. Enter that code, such as eu-west-1, in the wizard.
Offload failed: HTTP 404 NoSuchBucketNo bucket with that name exists.Copy the bucket name exactly from the S3 console and type it in the wizard.
Offload failed: HTTP 400 AccessControlListNotSupportedObject ACL is set to public-read, but the bucket has ACLs disabled.In Settings, Object Permissions, set Object ACL to private. Use CloudFront or a bucket policy for public access.
Offload failed: HTTP 403 RequestTimeTooSkewedYour server’s clock is too far from AWS time.Ask your host to sync the server clock.
Offload failed with an SSL certificate errorThe bucket name contains dots. AWS’s certificates do not cover these names.Create a bucket without dots and connect it instead.
Images are broken, or the file URL shows 403 AccessDeniedVisitors are not allowed to read the file.Option A: check the distribution uses origin access control and the bucket policy CloudFront added. Option B: check Block Public Access is off and the bucket policy is saved.
Images load from s3.amazonaws.com instead of your CDNCDN Configuration is set to Direct bucket URL, or the CDN URL is empty.Run the setup wizard, choose Custom CDN and enter the CDN URL. Or set WPMC_AWS_CDN_URL in wp-config.php.
New uploads stay on your serverOffload on upload is switched off. Before 1.1.7.1, finishing the setup wizard could switch it off.In Settings, turn on Offload on upload and Rewrite URLs.
Dashboard Storage Used shows no figureCloudWatch Stats is off, the policy has no cloudwatch:GetMetricStatistics, or AWS has not reported yet.Optional. Add the CloudWatch statement, tick CloudWatch Stats in the wizard, and wait a day. Offloading is not affected.
Browser console shows CORS errorsA script is fetched from the bucket’s domain, or a font while Serve fonts from your site is off. Fonts load from your site by default and need no CORS. Ordinary images and video do not need CORS.On the Health tab, run the Web Fonts (CORS) check and click Allow this site to add the rule to the bucket. If the button is not shown, your access key cannot change the bucket’s CORS rules: on the bucket’s Permissions tab, add a CORS rule that allows GET from your site’s address. With CloudFront, follow its CORS guidance as well.

Frequently asked questions#

Do I need CloudFront? No, but it is recommended. With CloudFront the bucket stays private and files are cached close to your visitors. Without it, you must make the whole bucket public (Option B).

Is a policy limited to one bucket really enough? Yes. It covers everything WP Media Cloud does with your files: uploading, serving, restoring and deleting. The wizard works with it too, because you type the bucket name. Only the optional Load list needs an account-wide permission.

Can I use the AmazonS3FullAccess managed policy instead? It works, but it gives the keys full control of every bucket in your account. If the keys leak, all your buckets are at risk. Use the inline policy in Step 3.

Does WP Media Cloud use object ACLs on S3? Not by default. With Object ACL on private, no ACL header is sent, which matches new buckets with ACLs disabled. Public access comes from CloudFront or the bucket policy instead.

Can I use an IAM role instead of access keys? No. WP Media Cloud signs every request with the Access Key ID and Secret Access Key you enter.

Which storage class are files stored in? WP Media Cloud does not set a storage class, so S3 stores files in S3 Standard.

How do I replace the access keys? An IAM user can have two access keys at a time. Create a second key, enter it with run the setup wizard, and check that new uploads still work. Then delete the old key in IAM.

Can I use one bucket for several sites? Yes, when each site has its own path prefix. WP Media Cloud stores files by upload date and file name, such as 2026/10/photo.jpg, so two sites without a prefix can overwrite each other’s files. On a multisite network, set Path prefix to sites/%site_id%. For separate sites, give each one a prefix of its own, such as shop and blog. A staging site should still use its own bucket. See Custom path prefix.

This website uses cookies to enhance your browsing experience and ensure the site functions properly. By continuing to use this site, you acknowledge and accept our use of cookies.

Accept All Accept Required Only