Configure Immutable Storage for Reseller and MSP Customers with Backblaze B2 Object Lock

Backblaze B2 Object Lock makes objects immutable for a defined retention period, helping resellers, MSPs, and storage platforms protect tenant backups from deletion and ransomware. Providers can isolate customers with separate B2 accounts, separate buckets, or prefix-restricted application keys. Governance mode permits authorized overrides, while compliance mode prevents retention from being shortened or removed until it expires.

For general feature behavior, see Object Lock.

How Object Lock Protects Tenant Data

Object Lock prevents an object version from being changed or deleted before its retention period expires. This provides a Write Once, Read Many (WORM) storage model for backup and retention workflows. An object remains readable and downloadable while it is locked.

Object Lock can help a reseller provide ransomware-resistant storage because an attacker cannot delete or overwrite a protected object version during its retention period. Object Lock does not prevent someone with valid credentials from reading data, uploading new objects, or taking actions outside the scope of the lock.

You can enable Object Lock when you create a bucket or on an existing bucket. After you enable Object Lock on a bucket, you cannot disable it. Enabling Object Lock alone does not make objects immutable. You must also configure default bucket retention or apply retention to individual objects.

Object Lock can support regulatory or legal retention requirements, but enabling it does not, by itself, make a service or customer compliant with a specific regulation. Compliance depends on the complete design, configuration, operational controls, and applicable requirements.

Choose a Tenant Isolation Model

Select the isolation model before you create buckets and application keys. The choice determines the administrative boundary, retention flexibility, reporting model, and impact of a compromised credential.

Use a separate account or bucket when tenants require independent default retention policies. Use a shared bucket with prefixes only when the tenants can share the bucket's default Object Lock configuration or your application applies retention to every object individually.

For account-per-tenant provisioning, see the Partner API. The Partner API creates and manages tenant accounts. Use the S3-Compatible API or B2 Native API after account creation to create buckets and configure Object Lock.

Compare Governance Mode and Compliance Mode

Backblaze B2 supports governance and compliance retention modes. Select the mode according to the level of administrative override that the service requires.

Do not give a tenant application key the bypassGovernance capability unless the tenant must be able to override governance retention. Keep administrative keys separate from application keys that perform routine uploads and downloads.

Plan Default and Per-Object Retention

You can apply retention in two ways:

• Default bucket retention: Automatically applies a retention mode and period to new objects uploaded or copied into the bucket.

• Per-object retention: Applies a specific mode and expiration date to an individual object version. A request can override the bucket default when the caller has the required capability and the requested change is permitted.

Default bucket retention does not retroactively protect existing objects. Apply retention to existing object versions separately when they must become immutable.

Legal Hold is separate from governance and compliance retention. A Legal Hold prevents deletion without a predetermined expiration date and remains in effect until an authorized caller removes it. You cannot configure Legal Hold as a bucket default.

Prepare the S3-Compatible API Credentials

Before you begin, gather the following information:

• The B2 S3 endpoint for the tenant's region, such as https://s3.us-west-004.backblazeb2.com

• A globally unique bucket name

• An application key ID and application key for the S3-Compatible API

• The tenant's required retention mode and retention period

The master application key is not supported by the S3-Compatible API. Create a standard application key for S3 access. Depending on the tasks that the key performs, it may require the following capabilities:

• writeBucketRetentions to enable Object Lock or configure default bucket retention

• readBucketRetentions to view the bucket Object Lock configuration

• writeFileRetentions and readFileRetentions to set and view object retention

• writeFileLegalHolds and readFileLegalHolds to set and view Legal Hold

• bypassGovernance only when the key is authorized to override governance-mode retention

• File and bucket capabilities required for the associated create, list, upload, download, or delete operations

If you restrict the application key to one bucket, include listAllBucketNames when the SDK or integration must use the S3 List Buckets operation. For more information, see S3-Compatible application keys.

The following examples use the AWS CLI and a profile named b2-reseller. Replace the placeholder values with your B2 endpoint, bucket name, and retention requirements.

aws configure --profile b2-reseller

Enter the application key ID as the AWS access key ID and the application key as the AWS secret access key. Enter the B2 region for the default region.

Create an Object Lock-Enabled Bucket

Use the S3 Create Bucket operation to create a bucket with Object Lock enabled.

aws s3api create-bucket \
  --bucket <tenant-bucket-name> \
  --object-lock-enabled-for-bucket \
  --endpoint-url https://s3.<region>.backblazeb2.com \
  --profile b2-reseller

Object Lock cannot be disabled after it is enabled. Verify the bucket name, tenant assignment, and region before you run this command.

You can also enable Object Lock on an existing eligible bucket. Backblaze B2 requires the x-amz-bucket-object-lock-token header with a value of 1 when you use the S3 Put Object Lock Configuration operation to enable it on an existing bucket. Confirm that your S3 client can add this header. If it cannot, use the B2 Native API or B2 CLI alternative described later in this article.

Configure Default Bucket Retention

The following example applies 30 days of compliance-mode retention to new objects uploaded or copied into the bucket.

aws s3api put-object-lock-configuration \
  --bucket <tenant-bucket-name> \
  --object-lock-configuration '{
    "ObjectLockEnabled": "Enabled",
    "Rule": {
      "DefaultRetention": {
        "Mode": "COMPLIANCE",
        "Days": 30
      }
    }
  }' \
  --endpoint-url https://s3.<region>.backblazeb2.com \
  --profile b2-reseller

Use GOVERNANCE instead of COMPLIANCE when authorized administrators must retain an override path. Test the configuration with nonproduction data before you apply compliance-mode retention to customer data.

Verify the bucket configuration:

aws s3api get-object-lock-configuration \
  --bucket <tenant-bucket-name> \
  --endpoint-url https://s3.<region>.backblazeb2.com \
  --profile b2-reseller

Apply Retention to an Individual Object

The following example uploads an object and retains that object version in compliance mode until the specified UTC date and time:

aws s3api put-object \
  --bucket <tenant-bucket-name> \
  --key tenant-a/backups/backup.tar \
  --body ./backup.tar \
  --object-lock-mode COMPLIANCE \
  --object-lock-retain-until-date 2027-01-01T00:00:00Z \
  --endpoint-url https://s3.<region>.backblazeb2.com \
  --profile b2-reseller

To view the retention settings, run the following command. Include --version-id <version-id> when you must inspect a specific object version.

aws s3api get-object-retention \
  --bucket <tenant-bucket-name> \
  --key tenant-a/backups/backup.tar \
  --endpoint-url https://s3.<region>.backblazeb2.com \
  --profile b2-reseller

Apply a Legal Hold

Use Legal Hold when an object must remain protected without a predetermined expiration date.

aws s3api put-object-legal-hold \
  --bucket <tenant-bucket-name> \
  --key tenant-a/backups/backup.tar \
  --legal-hold Status=ON \
  --endpoint-url https://s3.<region>.backblazeb2.com \
  --profile b2-reseller

Verify the Legal Hold status:

aws s3api get-object-legal-hold \
  --bucket <tenant-bucket-name> \
  --key tenant-a/backups/backup.tar \
  --endpoint-url https://s3.<region>.backblazeb2.com \
  --profile b2-reseller

Legal Hold and retention operate independently. An object remains protected if either control prevents deletion.

Use the B2 CLI as an Alternative

The B2 CLI uses the B2 Native API. The following example enables Object Lock on an existing bucket and configures 30 days of governance-mode default retention:

b2 bucket update \
  --file-lock-enabled \
  --default-retention-mode governance \
  --default-retention-period "30 days" \
  <tenant-bucket-name>

Upload an object with a specific retention expiration expressed as milliseconds since the Unix epoch:

b2 file upload \
  --file-retention-mode governance \
  --retain-until <timestamp-in-milliseconds> \
  <tenant-bucket-name> \
  ./backup.tar \
  tenant-a/backups/backup.tar

You can also configure Object Lock through the B2 Native API by using b2_update_bucket, b2_update_file_retention, and b2_update_file_legal_hold. See Enable Object Lock with the B2 Native API.

Apply Reseller Security Practices

• Use a separate application key for each tenant. Restrict it to the tenant's account, bucket, or filename prefix according to the selected isolation model.

• Keep the provider's administrative key separate from tenant and workload keys.

• Do not grant bypassGovernance to routine upload, download, or backup application keys.

• Enable multifactor authentication and restrict access to provider-level administrative accounts.

• Test restoration as well as immutability. Locked data is useful only when the backup application can restore it successfully.

• Confirm that the tenant's backup software supports S3 Object Lock and coordinates its retention policy with the bucket configuration.

• Monitor retained versions and storage consumption. Locked object versions continue to use storage until they can be deleted.

• Review Lifecycle Rules with the retention design. A Lifecycle Rule cannot delete an object version while Object Lock or Legal Hold prevents deletion.

Understand the Limits of Object Lock

Object Lock provides immutability, but it is not a complete security or compliance program.

• It prevents modification and deletion during the applicable retention period. It does not prevent authorized reading or downloading.

• Encryption and Object Lock address different risks. Encryption protects confidentiality, while Object Lock protects against modification and deletion.

• Governance mode can be bypassed by a caller with the bypassGovernance capability.

• Compliance-mode retention cannot be shortened or removed before it expires. An incorrect expiration date can retain data and associated storage costs longer than intended.

• Enabling Object Lock does not automatically protect existing objects or new objects when no default or per-object retention is configured.

• Legal Hold does not have an automatic expiration date and must be removed explicitly by an authorized caller.

• Object Lock does not replace application-key security, multifactor authentication, monitoring, or restore testing.

• Backup and synchronization tools that do not support Object Lock may fail when they attempt to change or delete protected object versions.

Frequently Asked Questions

Can an administrator delete a locked object?

In governance mode, a caller with the required capabilities can explicitly bypass governance protection. In compliance mode, no user can delete the object version or shorten its retention period before the retention date. An authorized caller can extend the retention date.

Does Object Lock stop ransomware?

Object Lock prevents protected object versions from being modified or deleted during their retention periods. This preserves recovery points when ransomware or a compromised credential attempts to change or remove backups. It does not prevent every action associated with an attack, so use it with strong account security, monitoring, encryption, and tested recovery procedures.

Should every tenant use compliance mode?

No. Use compliance mode when the tenant requires retention that no administrator can shorten or remove. Use governance mode when the service requires a tightly controlled administrative override. Document who can use that override and do not include bypassGovernance in routine tenant keys.

Can tenants in one bucket have different retention periods?

Yes, if the application sets retention on each object. However, default retention is configured at the bucket level and applies across tenant prefixes. Use a separate bucket when each tenant needs an independent default retention policy.

Can Object Lock be enabled on an existing bucket?

Yes, if the bucket is eligible. After you enable Object Lock, you cannot disable it. Existing object versions are not automatically protected, so apply retention or Legal Hold to any existing versions that must become immutable.