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 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 is the preferred browser-based explorer for Shade's S3 API. Filestash is open source 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 provides a browser-based file explorer for S3-compatible storage. To connect it to Shade:

1. Open 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 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, 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. 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.

# 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 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.