S3-Compatible Object Storage

Use this Drive with AWS S3 and compatible services such as COS, OSS, and MinIO.

Field	Description
Access Key / Secret Key	Access credentials
Bucket	Name of an existing bucket
Region	Service region; usually required for AWS
Endpoint	API address for a compatible service; may be left empty for AWS depending on the environment
Path style	Uses endpoint/bucket/key; often required by MinIO and similar services
Proxy upload/download	Forces file contents through go-drive
Request headers	Additional headers for requests sent by the go-drive server
Cache TTL	Entry cache time

The credentials need at least permission to list, read, write, copy, and delete objects in the target bucket. Create a dedicated least-privilege account for go-drive.

Custom request headers

Use Request headers for S3-compatible services that require an identifying header such as a custom User-Agent. The headers are added only when go-drive sends an HTTP request to the storage service. They are not included in presigned URLs and do not change direct-transfer behavior.

When proxy upload or download is disabled, that file transfer is performed by the browser and does not include the configured headers. Enable the corresponding proxy option if the storage service requires them on upload or download requests.

Configured values override headers generated earlier in request construction. S3 signing runs afterward and may replace headers it controls, such as Authorization. Connection-specific headers such as Host and Content-Length cannot be configured. Header values are stored and returned as ordinary Drive configuration; they are not secret-masked.

CORS for direct browser transfers

When proxy upload/download is disabled, the browser accesses S3 directly. The bucket's CORS policy must at least allow the go-drive site origin to use:

• Upload: PUT and POST, request headers content-type and x-amz-content-sha256, with etag exposed.
• Download: GET and HEAD.

AWS example:

[
  {
    "AllowedHeaders": ["content-type", "x-amz-content-sha256"],
    "AllowedMethods": ["PUT", "POST"],
    "AllowedOrigins": ["https://drive.example.com"],
    "ExposeHeaders": ["etag"]
  },
  {
    "AllowedHeaders": [],
    "AllowedMethods": ["GET", "HEAD"],
    "AllowedOrigins": ["https://drive.example.com"],
    "ExposeHeaders": []
  }
]

Also add the site domain to the object store's Referer or hotlink-protection allowlist. Do not use * instead of explicit domains and request headers in production.

Troubleshooting

• HeadBucket fails: check the endpoint, region, DNS, certificate, and credential permissions.
• Addressing errors with a compatible service: switch path-style mode.
• Browser uploads fail but background copies succeed: this is usually CORS or hotlink protection, not the S3 credentials.
• An internal-only site cannot access cloud direct links: enable proxy upload/download.