Docs

Backblaze B2

11 min readUpdated November 9, 2026

Backblaze B2 is low-cost, S3-compatible object storage. WP Media Cloud uploads your Media Library to a B2 bucket. It then serves every file from the bucket’s public address, or from a CDN in front of it. Backblaze offers free egress to its CDN partners, which include Cloudflare, Fastly and bunny.net.

This guide takes about 10 minutes.

Before you start#

  • A Backblaze account with B2 enabled. Backblaze also asks you to create a master application key before you can add other keys. WP Media Cloud does not use the master key.
  • A verified email address and a payment history. Backblaze requires both the first time you create a public bucket. Without a payment history, you can pay a small fee that is credited to your balance.
  • A CDN (recommended). Files served straight from the bucket count as B2 downloads. Serving them through a Backblaze CDN partner avoids those fees.
  • WP Media Cloud 1.1.8 or newer. It lets you type the bucket name in the setup wizard and keeps your CDN choice when you save Settings.

Step 1: Create a bucket#

  1. Sign in to the Backblaze web console.
  2. In the left menu, under B2 Cloud Storage, select Buckets.
  3. Select Create a Bucket.
  4. Enter a bucket name, for example example-media.
  5. Choose Public. See Step 2 for why.
  6. Leave Object Lock off.
  7. Select Create a Bucket.
  8. Copy the value in the Endpoint field, for example s3.us-west-004.backblazeb2.com. You need it in Step 4.

Bucket names are 6 to 63 characters and must be unique across all Backblaze accounts. Names starting with b2- are reserved. The bucket name becomes part of a web address, so use only lowercase letters, numbers and hyphens.

Find your region#

Your region is the middle part of the Endpoint. For s3.us-west-004.backblazeb2.com, the region is us-west-004. Enter the region only, not the full endpoint. You can find the Endpoint again on the Buckets page at any time.

Step 2: Make your files public#

Visitors must be able to load your images without keys. On Backblaze, public access is set per bucket, not per file. A Public bucket lets anyone download its files. Uploading, listing and deleting still need a key.

Your bucket’s public address is:

https://example-media.s3.us-west-004.backblazeb2.com

Replace example-media with your bucket name and us-west-004 with your region. WP Media Cloud uses this address automatically when you do not set a CDN.

If you already created a Private bucket: on the Buckets page, select Bucket Settings for the bucket. Choose Public and select Update Bucket. Backblaze says changes can take up to ten minutes.

About object ACLs: WP Media Cloud sends no ACL header to B2 by default. Backblaze applies the bucket’s setting to every file and does not support per-file ACLs. Leave Object ACL in Settings on private.

WP Media Cloud can serve files through one of these, chosen in the setup wizard or in Settings:

Option in WP Media CloudWhat it does
Direct bucket URL (wizard) or Direct Bucket (Settings)No CDN. Files load from the bucket address above.
Custom CDNAny CDN or custom domain, such as a Cloudflare-proxied subdomain. You type its URL.
Bunny.net CDNPaste a Bunny API key, select Load Zones, then pick your pull zone.
KeyCDNPaste a KeyCDN API key, load your zones and pick one.
EWWW Easy IOPaste your EWWW API key, load your sites and pick one.
CDN77Paste a CDN77 API token, load your resources and pick one.

Bunny, KeyCDN, EWWW and CDN77 also add CDN bandwidth figures to the Dashboard.

bunny.net: create a pull zone whose origin is your bucket’s public address from above. Backblaze recommends turning on Block Root Path Access in the pull zone’s security settings. Otherwise the zone’s root address lists your files.

Cloudflare: Backblaze documents serving a public bucket through Cloudflare with no download fees from Backblaze. You add a proxied CNAME, such as media.example.com, that points at your download host, such as f000.backblazeb2.com. You also add a URL Rewrite rule that adds /file/your-bucket-name to each path. Follow Backblaze’s Cloudflare guide, then use Custom CDN with https://media.example.com.

WP Media Cloud stores every file with a Cache-Control: public, max-age=31536000, immutable header. CDNs and browsers can cache each file for a year. Replaced files get a new file name, so this is safe.

Step 3: Create an application key#

You can limit this key to your one bucket. We recommend it.

  1. In the left menu, under B2 Cloud Storage, select Application Keys.
  2. Select Add a New Application Key.
  3. Enter a name, such as wp-media-cloud-example-com. Use letters, numbers and hyphens only.
  4. Under Allow Access to Bucket(s), choose your bucket.
  5. Optional: select Allow List All Bucket Names. It only lets the wizard’s Load button list your buckets. See the note below.
  6. Choose Read and Write access.
  7. Leave the file name prefix and the duration empty. If the key expires, your site stops offloading new uploads.
  8. Select Create New Key.
  9. Copy the keyID and the applicationKey into a password manager.

Copy the applicationKey now. Backblaze shows it only once. If you lose it, create a new key. The keyID stays visible on the Application Keys page.

Do you need Allow List All Bucket Names? No. You type the bucket name in the wizard. Load can fill a list to pick from, and a key limited to one bucket can only list buckets with this option. It lets the key see the names of your other buckets, but not their files.

Do not use the master application key. Backblaze does not support it with the S3-compatible API, which WP Media Cloud uses.

Step 4: Connect WP Media Cloud#

Setup wizard Connect step for Backblaze B2

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

FieldWhat to enter
RegionThe region from Step 1, for example us-west-004
Key IDThe keyID from Step 3
Application KeyThe applicationKey from Step 3
Bucket nameType your bucket name from Step 1, for example example-media
CDN ConfigurationDirect bucket URL to serve from the bucket, or one of the CDN options from Step 2
CDN URLOnly for Custom CDN. For example, https://media.example.com. Do not add the bucket name or a trailing path.

Load is optional. It fills a list of your buckets to pick from, if the key has Allow List All Bucket Names. It stays greyed out until Region, Key ID and Application Key are filled in.

The Backblaze screen has no Test connection button. WP Media Cloud checks access when it first uploads a file.

Step 5: Finish#

  1. Select Continue.
  2. On the All set! screen, select Save & Go to Dashboard.
  3. Upload a test image in Media > Add New Media File.
  4. Open the image in the Media Library and check that its file URL starts with your bucket address or CDN URL.
  5. Open that URL in a private browser window. The image should load.

If the image stays on your server or does not load, see Troubleshooting below.

Changing your bucket or keys later#

Backblaze B2 CDN card in Settings

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

The wizard opens with your saved region, bucket, CDN choice and CDN URL filled in. Saved keys show as Saved. Paste only the keys you are changing.

Alternative: Connect with wp-config.php#

wp-config.php constants for Backblaze B2 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. This 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',      'b2' );
define( 'WPMC_B2_REGION',     'us-west-004' );     // from your bucket's Endpoint
define( 'WPMC_B2_ACCESS_KEY', 'your-key-id' );     // keyID, not the master key
define( 'WPMC_B2_SECRET_KEY', 'your-application-key' ); // applicationKey
define( 'WPMC_B2_BUCKET',     'example-media' );

// Optional: serve through a CDN or custom domain.
// Without these, files load from https://example-media.s3.us-west-004.backblazeb2.com
define( 'WPMC_B2_CDN_TYPE',   'custom' ); // none | custom | bunny | keycdn | ewww | cdn77
define( 'WPMC_B2_CDN_URL',    'https://media.example.com' );

// Optional: object ACL. Default is private, which sends no ACL header.
define( 'WPMC_B2_ACL',        'private' ); // private | public-read
Code
// Required
define( 'WPMC_PROVIDER',      'b2' );
define( 'WPMC_B2_REGION',     'us-west-004' );     // from your bucket's Endpoint
define( 'WPMC_B2_ACCESS_KEY', 'your-key-id' );     // keyID, not the master key
define( 'WPMC_B2_SECRET_KEY', 'your-application-key' ); // applicationKey
define( 'WPMC_B2_BUCKET',     'example-media' );

// Optional: serve through a CDN or custom domain.
// Without these, files load from https://example-media.s3.us-west-004.backblazeb2.com
define( 'WPMC_B2_CDN_TYPE',   'custom' ); // none | custom | bunny | keycdn | ewww | cdn77
define( 'WPMC_B2_CDN_URL',    'https://media.example.com' );

// Optional: object ACL. Default is private, which sends no ACL header.
define( 'WPMC_B2_ACL',        'private' ); // private | public-read

The first five lines are required. The rest are optional.

For other CDNs, the generator also prints optional constants such as WPMC_B2_BUNNY_API_KEY, WPMC_B2_PULL_ZONE_HOSTNAME, WPMC_B2_KEYCDN_ZONE_URL, WPMC_B2_EWWW_API_KEY and WPMC_B2_CDN77_URL. WP Media Cloud reads every one of them. The Health page and the Dashboard read the constants too.

After setup#

  • New uploads go to B2 automatically and are served from your bucket address or CDN URL.
  • Existing media is not moved until you start a bulk offload. Open the Dashboard and select Offload All Media in the Bulk Offload card. On large libraries or multisite, wp wpmc offload (or wp wpmc offload --network) is faster.
  • Changing your CDN URL later: in Settings, open the Backblaze B2 CDN card. Choose your CDN option and enter the new URL. Under Apply to Existing Media, select Update all media URLs, then select Save Settings.
  • Dashboard stats: Backblaze does not report storage usage to WP Media Cloud, so Storage Used shows N/A. The file count comes from WP Media Cloud’s own records. Bandwidth appears only with Bunny, KeyCDN, EWWW Easy IO or CDN77 selected as your CDN.
  • WooCommerce secure downloads (signed, short-lived links) are available with Bunny.net and Cloudflare R2 only. For Backblaze B2, the WooCommerce card says so, and downloadable files use their normal CDN URL. Update WooCommerce Download URLs still works.

Troubleshooting#

Upload errors appear in the Bulk Offload card on the Dashboard, with the reason. They look like HTTP 403 AccessDenied: Access Denied.

What you seeWhat it meansHow to fix it
Load shows an errorBackblaze refused the bucket list. The key may lack Allow List All Bucket Names, the keys may be wrong, or the region may not match. The wizard shows the error below the field.Type the bucket name instead. Check the region against the bucket’s Endpoint.
Load is greyed outRegion, Key ID or Application Key is empty.Type the bucket name, or fill in all three.
InvalidAccessKeyId or SignatureDoesNotMatchThe keyID or applicationKey is wrong, or you used the master application key.Paste both again with no spaces at either end. Use a key you created in Step 3, not the master key.
AccessDenied or HTTP 403 on uploadThe key cannot write to this bucket.Check the key is limited to this bucket with Read and Write access. If not, create a new key (Step 3).
NoSuchBucket or HTTP 404The bucket name does not match.Type the bucket name exactly as shown on the Buckets page, or check WPMC_B2_BUCKET.
cURL error 6: Could not resolve hostThe Region field holds the full endpoint or a typo.Enter only the region, such as us-west-004.
“Backblaze B2 not fully configured. Missing: …”A required setting is empty.Run the setup wizard again, or check your wp-config.php constants.
Uploads fail after changing Object ACLBackblaze sets access per bucket. It returns an error when a file’s ACL differs from the bucket’s.Set Object ACL back to private in Settings. Change the bucket to Public instead (Step 2).
Images are broken on the site, or the file URL shows 401 or 403The bucket is Private.Change the bucket to Public (Step 2). Wait up to ten minutes, then reload.
Images are broken and the URL shows 404 through CloudflareThe URL Rewrite rule is missing, or it names the wrong bucket.Check the rule adds /file/your-bucket-name to the path, as in Backblaze’s Cloudflare guide.
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, then select Save Settings.
Browser console shows CORS errorsA script is fetched directly 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.Turn Serve fonts from your site back on, or add a CORS rule to the bucket that allows GET from your site’s address. WP Media Cloud cannot add this rule for Backblaze B2.

Frequently asked questions#

Can I limit the key to one bucket? Yes. Choose your bucket under Allow Access to Bucket(s) in Step 3. The key can then read and write only that bucket. With Allow List All Bucket Names it can also see other bucket names, but not their files.

Can I keep my bucket private? Only if a CDN signs its requests to B2. Backblaze documents this for bunny.net pull zones with S3 Authentication. The direct bucket address will not work for visitors. For most sites, a Public bucket is simpler.

Do I need a CDN? It is not required, but it is recommended. Files served straight from the bucket count as B2 downloads. Backblaze offers free egress to its CDN partners.

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.

Does B2 support object permissions (ACLs)? Only at bucket level. Every file follows the bucket’s Public or Private setting. WP Media Cloud sends no ACL header to B2 unless you change Object ACL in Settings.

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