Skip to content
Cloudflare Docs

Bucket locks

Bucket locks prevent the deletion and overwriting of objects in an R2 bucket for a specified period — or indefinitely. When enabled, bucket locks enforce retention policies on your objects, helping protect them from accidental or premature deletions.

Get started with bucket locks

Prerequisites

Before getting started, you will need:

  • An existing R2 bucket. If you do not already have an existing R2 bucket, refer to Create buckets.
  • An API token with permissions to edit R2 bucket configuration.

Enable bucket lock via API

Below is an example of setting a bucket lock configuration (a collection of rules):

Terminal window
curl -X PUT "https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/r2/buckets/<BUCKET_NAME>/lock" \
    -H "Authorization: Bearer <API_TOKEN>" \
    -H "Content-Type: application/json" \
    -d '{
        "rules": [
            {
                "id": "lock-logs-7d",
                "enabled": true,
                "prefix": "logs/",
                "condition": {
                    "type": "Age",
                    "maxAgeSeconds": 604800
                }
            },
            {
                "id": "lock-images-indefinite",
                "enabled": true,
                "prefix": "images/",
                "condition": {
                    "type": "Indefinite"
                }
            }
        ]
    }'

This request creates two rules:

  • lock-logs-7d: Objects under the logs/ prefix are retained for 7 days (604800 seconds).
  • lock-images-indefinite: Objects under the images/ prefix are locked indefinitely.

For more information on required parameters and examples of how to enable bucket lock, refer to the API documentation. For information about getting started with the Cloudflare API, refer to Make API calls.

Get bucket lock rules via API

For more information on required parameters and examples of how to get bucket lock rules, refer to the API documentation.

Bucket lock rules

A bucket lock configuration can include up to 1,000 rules. Each rule specifies which object it covers (via prefix) and how long those objects must remain locked. You can:

  • Lock objects for a specific duration. For example, 90 days.
  • Retain objects until a certain date. For example, until January 1, 2026.
  • Keep objects locked indefinitely.

If multiple rules apply to the same prefix or object key, the strictest (longest) retention requirement takes precedence.

Notes

  • Rules without prefix apply to all objects in the bucket.
  • Rules apply to both new and existing objects in the bucket.
  • Bucket lock rules take precedence over lifecycle rules. For example, if a lifecycle rule attempts to delete an object at 30 days but a bucket lock rule requires it be retained for 90 days, the object will not be deleted until the 90-day requirement is met.