> For the complete documentation index, see [llms.txt](https://academy.shade.inc/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://academy.shade.inc/developers/guides/using-shades-s3-api.md).

# Using Shade's S3 API

Use Shade Drives as an S3 Bucket

Shade exposes each drive as an S3-compatible bucket. Use it to move, sync, list, download, and upload files with an S3 client. Although we recommend [rclone](https://academy.shade.inc/guides/mass-migrating-data-to-shade-via-rclone) for most workflows; using Shade’s S3 API can unlock a wide variety of various use cases, integrations, and external connections.

### Before you begin

You need:

* A Shade account with **edit** access to the drive you want to use.
* **The drive ID. This UUID is the S3 bucket name, not the drive's display name.**
* An S3 access key created for your Shade account.

S3 keys are personal credentials. A key can access every drive for which its user has edit access. Creating a key does not grant access to a drive.

### Supported S3 actions

Shade’s S3 API can be accessed via `https://s3.shade.inc` and currently supports the following S3 actions:

* **ListBuckets** — list the Shade drives available to the S3 key owner.
* **HeadBucket** — check whether a drive exists and is accessible.
* **ListObjects** — list the objects in a drive. When supplied, `delimiter` must be `/`, and `prefix` must be a path-like value with no leading `/` and a trailing `/` (for example, `deliverables/`).
* **ListObjectsV2** — list the objects in a drive, with the same `delimiter` and `prefix` restrictions as `ListObjects`.
* **HeadObject** — inspect an object's metadata.
* **GetObject** — download an object.
* **PutObject** — upload or replace a single object.
* **CopyObject** — copy an object to another key in the same drive.
* **RenameObject** — move a file to another key in the same drive. The destination must not already exist, and neither key can end in `/`. Conditional rename headers are not supported, and client tokens do not provide idempotent retries.
* **DeleteObject** — delete an object.
* **DeleteObjects** — delete multiple objects in one request. Version IDs and per-object delete conditions are not supported.
* **CreateMultipartUpload** — start an upload for a large object.
* **UploadPart** — upload one part of a multipart upload.
* **ListParts** — list the parts uploaded for an in-progress multipart upload.
* **CompleteMultipartUpload** — assemble a multipart upload after its parts have been uploaded.
* **AbortMultipartUpload** — cancel an in-progress multipart upload.

Buckets are existing Shade drives: do not try to create or delete buckets with an S3 client. Other S3 actions are not supported today; we plan to add more over time.

### Create and manage S3 keys

#### In the Shade web app

1. Open a workspace you can access.
2. Go to **Settings → Integrate → S3 API keys**.
3. Select **Generate S3 API key**.
4. Give the key a recognizable name and choose an expiration, if wanted.
5. Copy the access key ID and secret access key before selecting **Done**.

The secret access key is displayed only in the creation dialog. Store it in a password manager or another secret store immediately. If it is lost, create a replacement key and delete the old one from the same page. Deleting a key revokes it immediately; expiry also prevents new S3 requests from using it.

### Example Use Cases: Browse files with Filestash

[Filestash's S3 browser](https://www.filestash.app/s3-browser.html) is the preferred browser-based explorer for Shade's S3 API. Filestash is [open source](https://github.com/mickael-kerjean/filestash) and can be self-hosted. S3 Viewer is currently closed source, so prefer Filestash when you want a browser-based client whose code you can inspect and run yourself.

1. Set the **Endpoint** to `https://s3.shade.inc`.
2. Enter your own Shade S3 **Access Key ID** and **Secret Access Key**.
3. Open the bucket named with your Shade drive UUID to browse its files.

To return to your bucket later, revisit the login page with the appropriate endpoint and enter your own keys again. Bookmark the login page without keys in the URL: a URL containing your secret key can be saved in browser history or shared accidentally. The public demo receives your credentials to connect to Shade; use a dedicated, revocable S3 key, or self-host Filestash if you prefer. Shade keys can access every drive for which their owner has edit access.

Shade buckets are existing drives, so do not use any **Create Bucket** action.

#### Alternative: S3 Viewer

[S3 Viewer](https://s3-viewer.com/) provides a browser-based file explorer for S3-compatible storage. To connect it to Shade:

1. Open [s3-viewer.com/dashboard](https://s3-viewer.com/dashboard) and select **Connect server** or **Add new server**.
2. Enter a recognizable name, such as `Shade Drive`.
3. Set **Region** to `us-east-1`.
4. Set **Endpoint** to `https://s3.shade.inc` for production.
5. Enter your Shade S3 access key ID and secret access key.
6. Continue, review the detected server, and select **Connect**.
7. Open a bucket to browse its files. Each bucket is identified by its Shade drive UUID rather than its display name.

Do not use S3 Viewer's **Create Bucket** action: Shade buckets are existing drives and cannot be created through the S3 API.

S3 Viewer is a third-party service, so it must receive credentials to perform S3 operations. Its website states that credentials are encrypted at rest. Use a dedicated, revocable Shade S3 key and remember that the key can access every drive for which its owner has edit access.

### Example Use Case: Browse files with Cyberduck

[Cyberduck](https://cyberduck.io/s3/) is an open-source desktop client for browsing S3-compatible storage on macOS and Windows.

Shade requires path-style S3 requests. Install Cyberduck's [S3 path-style connection profile](https://profiles.cyberduck.io/S3%20\(Deprecated%20path%20style%20requests\).cyberduckprofile), then configure a connection:

1. Open the downloaded connection profile in Cyberduck to install it.
2. Create a new bookmark using **S3 (Deprecated path style requests)**.
3. Set **Server** to `s3.shade.inc` and use port `443` with SSL enabled.
4. Enter your Shade S3 **Access Key ID** and **Secret Access Key**.
5. Connect, then open the bucket named with your Shade drive UUID.

If Cyberduck reports a DNS or container-configuration error, confirm that you selected the path-style profile rather than the standard S3 profile. Do not create a bucket: Shade buckets are existing drives.

### Configure the AWS CLI

Install AWS CLI v2 using the [AWS CLI installation guide](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html). Put the endpoint and path-style setting in `~/.aws/config`:

```
region = us-east-1
endpoint_url = https://s3.shade.inc
s3 = addressing_style = path
```

Put the credentials in `~/.aws/credentials`:

```
aws_access_key_id = your-access-key-id
aws_secret_access_key = your-secret-access-key
```

`addressing_style = path` is the AWS CLI equivalent of rclone's required `force_path_style = true`. Do not omit it.

```bash
# List objects in the drive
aws s3 ls s3://$DRIVE_ID/

# Upload and download
aws s3 cp ./clip.mov s3://$DRIVE_ID/incoming/clip.mov
aws s3 cp s3://$DRIVE_ID/incoming/clip.mov ./clip.mov

# Inspect or remove one object
aws s3api head-object --bucket "$DRIVE_ID" --key incoming/clip.mov
aws s3 rm s3://$DRIVE_ID/incoming/clip.mov
```

For production, create a separate profile with `endpoint_url = https://s3.shade.inc`, a non-empty region (the examples use `us-east-1`), and the same path-style setting.

### Example Use Case: Back up a Synology NAS with Hyper Backup

[Synology Hyper Backup](https://www.synology.com/en-us/dsm/feature/hyper_backup) can back up NAS folders and packages to S3-compatible destinations with scheduling, rotation, compression, and optional client-side encryption.

1. In DSM, install and open **Hyper Backup**.
2. Create a **Data backup task** and choose **S3 Storage** as the destination.
3. For **S3 server**, select **Custom Server URL** and enter `https://s3.shade.inc`.
4. Select signature version **V4**. Synology supports path-style buckets with a custom server URL only when V4 signing is used.
5. Enter a dedicated Shade S3 access key ID and secret access key.
6. Select or enter the bucket using the Shade drive UUID, then choose a directory for the backup.
7. Select the folders and packages to protect, configure a schedule and rotation policy, and enable client-side encryption if needed.
8. Run the first backup, then perform a test restore before relying on the task for production recovery.

Shade supports a subset of S3 actions. Hyper Backup behavior can vary by DSM and package version, so setup or maintenance operations that call an unsupported action may fail. Use a dedicated, revocable key and verify both backup and restore after updates. Remember that the key can access every drive for which its owner has edit access.

### Troubleshooting

* **403 Forbidden:** Check that the key has not expired or been deleted, and that its owner still has edit access to the drive.
* **Signature mismatch or requests going to `<bucket>.s3…`:** Make sure path style is enabled (`force_path_style = true` in rclone or `addressing_style = path` in AWS CLI) and that the region is non-empty.
* **Bucket creation errors:** Use an existing drive UUID as the bucket and enable rclone's `no_check_bucket = true`. Shade does not create S3 buckets yet.
* **Lost secret access key:** It cannot be recovered. Generate a new key and revoke the old one.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://academy.shade.inc/developers/guides/using-shades-s3-api.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `build a script that syncs our docs to a CMS` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.