Minimum S3 permissions for restic backups and pruning

Restic stores configuration, keys, snapshots, indexes, locks, and data packs as objects. A normal backup client must list the repository, read existing metadata and data, write new objects, and delete locks or obsolete objects. Retention and pruning make delete access unavoidable on that client. On Amazon S3, the client commonly also needs s3:GetBucketLocation to resolve the bucket correctly.

Read-only credentials can handle many recovery tasks, including listing and restoring existing snapshots, when the command supports --no-lock. Use that flag only when you know no writer or maintenance job is changing the repository. Read-only access is insufficient for routine backups, maintenance, or lock cleanup, so a separate recovery key does not replace the active backup credential.

• List: discover repository objects beneath the configured prefix.
• Read: open repository configuration, indexes, snapshots, packs, and locks.
• Write: initialize the repository and upload new metadata, packs, and locks.
• Delete: remove locks and reclaim data during forget and prune.

In Amazon S3 IAM, ListObjectsV2 maps to s3:ListBucket and targets the bucket ARN. GetObject, PutObject, and DeleteObject target object ARNs. Mixing those resource types is a common reason a policy looks correct but returns AccessDenied.

A least-privilege policy therefore needs a bucket-level statement for location and prefix-constrained listing, plus object-level read, write, and delete access for the repository prefix. Use the current AWS and restic examples to produce the actual JSON; do not copy a policy from an unrelated bucket layout.

Restricting object actions to bucket/prefix/* prevents the credential from reading or changing objects elsewhere in the bucket. Listing is a bucket-level action, so AWS uses an s3:prefix condition to limit which keys a ListObjects request may return. Depending on the client’s request shape, the allowed values may need both the prefix itself and prefix/*.

Do not paste an AWS policy unchanged into every S3-compatible service. Some providers implement only part of IAM’s condition language, some scope credentials through their own UI, and some need a broader list capability for SDK compatibility. Start with the provider’s documented mechanism, then test the exact endpoint and prefix with the same client used for backups.

The names differ, but the required object operations do not. Use a dedicated machine credential and keep account administration out of its scope.

• Cloudflare R2: create an Object Read & Write S3 API token and apply it only to the backup bucket. Use the Access Key ID and Secret Access Key shown when the token is created.
• Backblaze B2: a restricted application key may need listAllBucketNames for S3 SDK compatibility, plus listFiles, readFiles, writeFiles, and deleteFiles for the repository. Backblaze documents the exact S3 calls behind those capabilities.
• Wasabi: attach a bucket- or folder-restricted IAM policy to a dedicated sub-user, then create that user’s access key. Console access and broad S3 administration are unnecessary for the backup process.
• MinIO: attach a policy to a dedicated user and create an access key that inherits, or further narrows, that policy. MinIO denies operations that are not explicitly allowed.

An existing-bucket restic setup does not need to create or delete buckets, change bucket policies, manage users, configure public access, edit lifecycle rules, or administer replication. It also does not need wildcard access to every bucket in the account.

Extra permissions can appear necessary when a provider’s web console performs account-level discovery before showing a bucket. The backup agent does not need to browse that console. Separate console convenience from the S3 API calls the backup process actually makes, except where the provider explicitly requires a compatibility capability such as Backblaze’s listAllBucketNames.

A policy review catches obvious overreach; a disposable-object test catches endpoint, region, scope, and compatibility mistakes. Verify the credential against its intended scope without touching an existing repository object.

Rested validates destination setup and reports actionable configuration errors before a backup is attempted. The implementation stays inside the product; operators only need the result and a useful error.

Bucket and prefix scope limits lateral damage, but the active backup credential can still delete its own repository. Store it in a root-only secret store, keep it out of shell history and logs, rotate it, and alert on unusual object deletion. Disable the old key only after a backup, prune, and restore test succeeds with the replacement.

For stronger deletion resistance, send another copy to an immutable or append-only target and keep its maintenance credential away from the protected host. Applying object lock directly to an active restic repository needs careful testing because restic maintenance rewrites and deletes objects. An isolated protected copy is easier to reason about during an incident.