# Cloudflare R2

> Connect Cloudflare R2 buckets to BucketMate with an S3 API token

Canonical: https://docs.bucketmate.app/macos/providers/connect-cloudflare-r2

BucketMate connects to Cloudflare R2 through the S3-compatible API endpoint for your account.

## Prerequisites

- Cloudflare account
- R2 bucket
- Account ID
- R2 API token with access key ID and secret access key

## Endpoint and region

Use your account-specific endpoint:

```text
https://<account-id>.r2.cloudflarestorage.com
```

Set region to:

```text
auto
```

## Permissions

Give the token access to the buckets you want to manage. BucketMate may need permission to list buckets, list objects, read objects, write objects, and delete objects depending on the actions you use.

If the token is scoped to specific buckets and cannot list all buckets, turn off **Credentials have permission to list buckets** and enter bucket names manually.

## Connection steps

1. Open the Cloudflare dashboard.
2. Go to R2 and create or select an API token for S3 access.
3. Copy the account ID, access key ID, and secret access key.
4. Open BucketMate.
5. Choose **Add Connection**.
6. Select **Cloudflare R2**.
7. Enter the endpoint `https://<account-id>.r2.cloudflarestorage.com`.
8. Enter region `auto`.
9. Enter the access key ID and secret access key.
10. Use **Test Connection**.
11. Save the connection.

## Common issues and fixes

### Region must be auto

Some tools require a region value, and R2 expects `auto`. Fix by setting the region to `auto` - empty and `us-east-1` are accepted aliases.

### ACL headers are not supported

Requests using `x-amz-acl` will fail. Fix by removing ACL headers and using R2 access controls instead of S3 ACL calls.

### Object Lock is not supported

Object Lock headers are not implemented. Fix by removing Object Lock headers and using provider-native retention controls if required.

### Tagging headers are not supported

Requests using `x-amz-tagging` will fail. Fix by removing tagging headers and storing tags in metadata or your app database.

### SSE-KMS is not supported

SSE-KMS headers are not implemented. Fix by using SSE-C or client-side encryption.

### Direct object URLs do not open

R2 buckets are private by default. Use BucketMate's presigned share links for private objects, or configure public access and a custom domain if you want copied direct URLs to work in a browser.

## BucketMate tips

- Add a bucket custom domain in BucketMate when you want **Copy URL (custom domain)** to use your public R2 domain.
- Use presigned links for private one-off sharing.
- Use manual bucket names for restricted R2 tokens.