Docs

Wasabi

9 min readUpdated November 9, 2026

Wasabi is S3-compatible object storage. WP Media Cloud uploads your Media Library to a Wasabi bucket. It serves every file from there, either directly or through a CDN in front.

This guide takes about 15 minutes. It uses WP Media Cloud 1.1.8 and a Wasabi sub-user that can reach only your one bucket.

Check public access first#

WP Media Cloud serves your media from public URLs. Visitors, and any CDN you put in front, read files from the bucket without keys. So the bucket must allow public reads.

Wasabi restricts this on some accounts:

  • Trial accounts cannot make files public. Wasabi has disabled the public access feature for trial users.
  • Accounts created on or after March 13, 2023 cannot enable public access in the Console or CLI.

If either applies to you, contact Wasabi Support before you start, and ask them to review your use case. Without public access, files upload but your site cannot show them.

Before you start#

  • A paid Wasabi account with public access available. See above.
  • A CDN (recommended). Wasabi’s free egress policy fits when your monthly downloads are no larger than the data you store. If you regularly exceed that, Wasabi may limit or suspend your service. A CDN caches files and cuts the downloads from your bucket.
  • WP Media Cloud 1.1.8 or newer is recommended. Its setup wizard works with a sub-user limited to one bucket.

Step 1: Create a bucket#

  1. Sign in to the Wasabi Console at console.wasabisys.com. The Buckets page opens.
  2. Select Create Bucket.
  3. Under Bucket Name, enter a name. Names use 3 to 63 lowercase letters, numbers, periods and dashes, and must be unique across Wasabi. For example, example-media.
  4. Under Select Region, pick the region closest to most of your visitors.
  5. Leave versioning, logging and Object Lock off.
  6. Select Create.

Note the region code, such as us-east-1 or eu-central-2. The Console shows the region’s service URL next to its name.

Step 2: Allow public reads#

Wasabi buckets are private by default. WP Media Cloud sends x-amz-acl: public-read with every upload, which makes each new file public if your account allows it.

To make every file in the bucket readable, including files already there, also add a bucket policy:

  1. On the Buckets page, open the menu for your bucket and select Settings.
  2. Open the Permissions tab.
  3. Select Edit and paste the policy below. Replace example-media with your bucket name.
  4. Select Save.
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowPublicRead",
      "Effect": "Allow",
      "Principal": { "AWS": "*" },
      "Action": [ "s3:GetObject", "s3:GetObjectVersion" ],
      "Resource": "arn:aws:s3:::example-media/*"
    }
  ]
}

This policy lets anyone read files, but not list, change or delete them. Do not store anything private in this bucket.

WP Media Cloud works with these CDNs for Wasabi: Custom CDN (such as CloudFront or Fastly), Bunny.net CDN, KeyCDN, EWWW Easy IO and CDN77.

In your CDN, create a pull zone or resource with your bucket as the origin:

  • Most regions: https://example-media.s3.eu-central-2.wasabisys.com
  • us-east-1: https://example-media.s3.wasabisys.com

Note the CDN address it gives you, such as https://example.b-cdn.net, or your own subdomain. WP Media Cloud stores every file with a one-year Cache-Control header, so the CDN and browsers keep files for a year.

Without a CDN, files are served from https://s3.eu-central-2.wasabisys.com/example-media. This is fine for testing.

Step 4: Create a sub-user limited to one bucket#

Wasabi recommends not using your root account’s keys for everyday access. Instead, create a policy for your one bucket, then a sub-user with that policy.

Create the policy#

  1. In the Wasabi Console, select Policies in the left menu.
  2. Select Create Policy.
  3. Name it, for example wp-media-cloud-example-media.
  4. Paste the policy below. Replace example-media with your bucket name.
  5. Save the policy.
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "s3:*",
      "Resource": [
        "arn:aws:s3:::example-media",
        "arn:aws:s3:::example-media/*"
      ]
    }
  ]
}
Code
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "s3:*",
      "Resource": [
        "arn:aws:s3:::example-media",
        "arn:aws:s3:::example-media/*"
      ]
    }
  ]
}

This statement gives full access to your one bucket only.

Optional: to let the wizard’s Load button list your bucket names, add this statement to the Statement list. It cannot read or change other buckets. You can skip it, because you type the bucket name in the wizard.

{
  "Effect": "Allow",
  "Action": "s3:ListAllMyBuckets",
  "Resource": "arn:aws:s3:::*"
}

Create the sub-user#

  1. Select Users in the left menu, then Create User.
  2. Enter a name, for example wp-media-cloud-example-com.
  3. Under access type, tick Programmatic (the user can create an API key). Leave Console access unticked.
  4. Select Next. Skip the group step, or add a group, then select Next.
  5. Under Attach Policy To User, choose the policy you just created. Attach nothing else.
  6. Select Next, review, then select Create User.
  7. Copy the Access Key and Secret Key into a password manager, or download them.

Save the keys now. If you do not download or copy them now, Wasabi will not show the secret key again. Each user can have only two access keys.

Step 5: Connect WP Media Cloud#

Setup wizard Connect step for Wasabi

In WordPress, open Media Cloud in the admin menu. The setup wizard opens on first use. Choose Wasabi and select Continue.

FieldWhat to enter
RegionYour bucket’s region, for example eu-central-2. The menu starts on us-east-1.
Access KeyFrom Step 4
Secret KeyFrom Step 4
Bucket nameType your bucket name from Step 1, for example example-media. If you added the optional list statement, you can select Load and pick it instead.
CDN ConfigurationYour CDN from Step 3. Choose Direct bucket URL for no CDN.
CDN URLFor Custom CDN, enter your CDN address, for example https://media.example.com. For Bunny.net, KeyCDN, EWWW Easy IO and CDN77, paste the API key and pick your zone, site or resource. The CDN URL fills in.

The wizard has no Test connection button for Wasabi. You check the connection in Step 6.

Changing your bucket or keys later#

CDN card in Settings

Go to Settings and select run the setup wizard. Your offloaded files and records are kept. In WP Media Cloud 1.1.8 or newer, the wizard opens with your saved region, bucket, CDN choice and CDN URL. Saved keys show as Saved. Paste only the keys you are changing.

Step 6: Finish and check#

  1. Select Continue, then Save & Go to Dashboard.
  2. Go to Settings and check that Offload on upload and Rewrite URLs are both on.
  3. Upload a test image to the Media Library.
  4. Open the image and copy its file URL. It should start with your CDN URL and open in your browser.

If the upload fails, the reason is listed in the Bulk Offload card on the Dashboard. See Troubleshooting below.

The Health tab checks that your settings are complete and that the CDN URL answers. It does not upload a test file.

Alternative: Connect with wp-config.php#

wp-config.php constants for Wasabi 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',          'wasabi' );
define( 'WPMC_WASABI_REGION',     'eu-central-2' ); // your bucket's region code
define( 'WPMC_WASABI_ACCESS_KEY', 'your-access-key' );
define( 'WPMC_WASABI_SECRET_KEY', 'your-secret-key' );
define( 'WPMC_WASABI_BUCKET',     'example-media' );

// Optional: serve through a CDN or your own subdomain.
define( 'WPMC_WASABI_CDN_TYPE',   'custom' );
define( 'WPMC_WASABI_CDN_URL',    'https://media.example.com' );

// Optional: object ACL. The default is public-read.
define( 'WPMC_WASABI_ACL',        'public-read' ); // public-read | private
Code
// Required
define( 'WPMC_PROVIDER',          'wasabi' );
define( 'WPMC_WASABI_REGION',     'eu-central-2' ); // your bucket's region code
define( 'WPMC_WASABI_ACCESS_KEY', 'your-access-key' );
define( 'WPMC_WASABI_SECRET_KEY', 'your-secret-key' );
define( 'WPMC_WASABI_BUCKET',     'example-media' );

// Optional: serve through a CDN or your own subdomain.
define( 'WPMC_WASABI_CDN_TYPE',   'custom' );
define( 'WPMC_WASABI_CDN_URL',    'https://media.example.com' );

// Optional: object ACL. The default is public-read.
define( 'WPMC_WASABI_ACL',        'public-read' ); // public-read | private

The first five constants are required. Without WPMC_WASABI_CDN_URL, files are served from https://s3.eu-central-2.wasabisys.com/example-media.

For other CDNs, the generator also prints optional constants such as WPMC_WASABI_BUNNY_API_KEY, WPMC_WASABI_PULL_ZONE_HOSTNAME, WPMC_WASABI_KEYCDN_ZONE_URL, WPMC_WASABI_EWWW_API_KEY and WPMC_WASABI_CDN77_URL. WP Media Cloud reads every one of them. The Health tab and the Dashboard read the constants too.

After saving the file, open Media Cloud. If the wizard appears, select Configure via wp-config.php, then Done, constants added, so the plugin detects your constants.

After setup#

  • New uploads go to Wasabi automatically and are 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: update it in the Wasabi CDN card in Settings. Then select Update all media URLs so existing offloaded items use the new address.
  • Dashboard stats: the Dashboard counts your offloaded files. Storage Used shows 0 B, because the plugin does not read storage size from Wasabi. CDN Bandwidth shows figures with Bunny.net, KeyCDN, EWWW Easy IO or CDN77, chosen in Settings.
  • WooCommerce secure downloads are available with Bunny.net and Cloudflare R2 only. For Wasabi, the WooCommerce card says so, and downloadable files use their normal CDN URL.
  • Object Permissions: the ACL sent with each upload is in Settings, under Object ACL. You can choose private if your bucket policy from Step 2 already makes files public.
  • Minimum storage time: on Pay as You Go, Wasabi charges for at least 90 days per file. Deleting media sooner still costs the remaining days.

Troubleshooting#

What you seeWhat it meansHow to fix it
Load shows HTTP 403 AccessDeniedThe sub-user’s policy does not allow listing buckets. The wizard shows the error below the field.Type the bucket name instead. Or add the optional s3:ListAllMyBuckets statement from Step 4.
HTTP 403 InvalidAccessKeyIdThe access key does not exist, or was deleted.Paste the access key again, or create a new key for the sub-user.
HTTP 403 SignatureDoesNotMatchThe secret key is wrong.Paste the secret key again. If you are unsure of it, create a new key.
Bulk Offload lists HTTP 403 AccessDeniedThe sub-user cannot write to this bucket.Check that the policy is attached to the sub-user and names this exact bucket in both Resource lines.
HTTP 404 NoSuchBucketThe bucket name does not match.Copy the bucket name exactly as shown in the Console.
Uploads fail with an error about the region or endpointThe region does not match the bucket.Check the region shown for your bucket in the Console and choose the same one.
Images are broken, or the file URL shows 403The bucket does not allow public reads.Add the bucket policy from Step 2. On trial accounts and newer accounts, ask Wasabi Support to enable public access.
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.

Errors from Load appear below the Bucket name field. Errors from uploads are listed in the Bulk Offload card on the Dashboard. You can also run wp wpmc failed.

Frequently asked questions#

Why does Wasabi need public access? Your site links straight to each file’s URL. Visitors’ browsers and your CDN fetch files without keys. That only works if the bucket allows public reads.

Can the sub-user touch my other buckets? No. It cannot read, change or delete anything outside your one bucket. With the optional s3:ListAllMyBuckets statement, it can also list bucket names.

Does serving images count towards Wasabi’s egress policy? Yes. Every file a visitor downloads from the bucket counts. A CDN serves repeat requests from its cache, so far fewer downloads reach Wasabi.

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.

Which regions are supported? All 16 Wasabi regions in the wizard’s Region menu, from us-east-1 to ap-southeast-2. Use the code that matches your bucket.

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