# Connect storage

> Add, import, test, edit, and delete S3-compatible connections in BucketMate for iOS

Canonical: https://docs.bucketmate.app/ios/features/connect-storage

A connection stores the endpoint, region, and credentials BucketMate uses to reach your storage. You can add one manually or import it from BucketMate on your Mac with a QR code.

## Add a connection manually

1. On **Connections**, tap **+**. If you have no connections yet, tap **Add connection manually**.
2. In **Connection**, enter a **Name**.
3. Tap **Provider** and choose your storage service.
4. In **Server**, enter the endpoint and tap **Region** to choose a region.
5. In **Credentials**, enter the **Access key ID** and **Secret access key**. Tap the eye icon to show or hide the secret.
6. Tap **Test connection**. The button turns green and shows **Connection successful** when BucketMate can reach your storage.
7. Tap **Connect**. BucketMate saves the connection and opens its bucket list.

Tap **Setup guide** under the provider row to open the provider's documentation for creating access keys.

## Connection fields

| Field | How to use it |
| --- | --- |
| Name | Required. Label shown in the connection list. |
| Provider | **Amazon S3**, **Google Cloud Storage**, **Cloudflare R2**, **Backblaze B2**, **DigitalOcean Spaces**, **Wasabi**, **Supabase Storage**, **Hetzner Object Storage**, **Tigris**, **MinIO**, or **Custom S3-compatible**. |
| Endpoint | Optional for Amazon S3. Required for every other provider. |
| Virtual-hosted style | Shown for MinIO and Custom S3-compatible. Puts the bucket name in the hostname instead of the path. See [Virtual-hosted style](#virtual-hosted-style). |
| Region | Pick from the list, search with **Search regions**, or choose **Custom region** to type any value. |
| Access key ID | Required. Provider access key, HMAC key, or application key ID. |
| Secret access key | Required. Matching secret for the access key. |
| Load all buckets | Keep on when credentials can list buckets. Turn off to enter bucket names manually. |

BucketMate checks the endpoint when you save:

- Google Cloud Storage endpoints must contain `storage.googleapis.com`.
- Cloudflare R2 endpoints must contain `r2.cloudflarestorage.com`.
- Supabase endpoints must contain `supabase.co`.
- Hetzner endpoints must contain `your-objectstorage.com`.
- Tigris endpoints must contain `storage.dev` or `tigris.dev`.
- Backblaze B2 endpoints must contain `backblazeb2.com`.
- DigitalOcean Spaces endpoints must contain `digitaloceanspaces.com`.
- Wasabi endpoints must contain `wasabisys.com`.
- MinIO and Custom S3-compatible endpoints must use HTTPS. `http://` endpoints are not supported.

If you type an endpoint that matches a known provider, BucketMate switches the **Provider** to match.

## Import from your Mac with a QR code

Quick Connect copies a connection from BucketMate for macOS without typing keys on your phone.

1. On your Mac, right-click a connection in BucketMate and choose **Show QR for mobile**.
2. On your iPhone, tap **Scan QR code** on the empty **Connections** screen, or open **New connection** and tap **Scan QR code** (**Import from your Mac**).
3. Allow camera access when asked.
4. Point the camera at the QR code. Tap **Turn on light** if the room is dark.
5. Review the filled-in fields, then tap **Test connection** and **Connect**.

Quick Connect does not support AWS SSO connections from the Mac app. If the camera is blocked, BucketMate shows **Camera access required** with a shortcut to **Settings**.

## Limited bucket permissions

Some credentials can read objects but cannot list all buckets.

1. In **Buckets**, turn off **Load all buckets**.
2. Enter bucket names, one per line or separated by commas.
3. Tap **Test connection**, then **Connect**.

BucketMate shows only the buckets you entered.

## Single-bucket endpoints

If the endpoint already contains a bucket name, BucketMate treats it as a single-bucket connection. **Load all buckets** turns off and locks, and the **Server** footer shows **Endpoint restricted to single bucket**.

| Endpoint style | Example |
| --- | --- |
| Path-style | `https://storage.example.com/my-bucket` |
| Virtual-hosted | `https://my-bucket.storage.example.com` |

## Virtual-hosted style

S3 requests can address a bucket in two ways:

| Style | Request URL |
| --- | --- |
| Path-style | `https://storage.example.com/my-bucket/photo.jpg` |
| Virtual-hosted style | `https://my-bucket.storage.example.com/photo.jpg` |

BucketMate uses path-style for custom endpoints by default. Most S3-compatible servers accept it, and it works without wildcard DNS or certificates.

Some providers accept only virtual-hosted style. They reject path-style requests with errors such as `SecondLevelDomainForbidden`, **Please use virtual hosted style**, or `403 Access denied`. Alibaba Cloud OSS is one example.

To use virtual-hosted style:

1. Select **MinIO** or **Custom S3-compatible** as the provider.
2. Enter the endpoint without a bucket name, such as `https://oss-ap-southeast-1.aliyuncs.com`.
3. Turn on **Virtual-hosted style**.
4. Test the connection.

Turn it on only when your provider requires it:

- Your provider's DNS and TLS certificate must cover `<bucket>.<endpoint host>`. Some providers, such as Hetzner, issue certificates that do not cover bucket subdomains, so keep the option off for them.
- Bucket names that contain dots may fail over HTTPS because they do not match a wildcard certificate.

Copied object URLs follow the style you choose.

## Edit, refresh, or delete a connection

On **Connections**, swipe left on a connection:

- **Edit** opens the connection form. Tap **Save** to apply changes.
- **Delete** asks for confirmation, then removes the connection from this device.

Touch and hold a connection for **Open**, **Edit**, **Refresh**, and **Delete**. **Refresh** opens the bucket list and reloads bucket data from the provider.

You can also tap the pencil icon on a connection's bucket list to edit it. Saving changes clears that connection's cached data.

## Free version limit

The free version allows one connection. Adding a second connection, manually or by QR code, shows **Trial version limit**. Tap **Buy now** to open the upgrade screen. See [BucketMate Pro](/ios/features/bucketmate-pro).