S3-compatible object API
The S3 endpoint handles object bytes directly. Use the endpoint and region displayed in your Storage project; the Dashboard JSON API uses a different host and authentication scheme.
Connect an S3 client
- Create a project access key with
readorreadwritepermission and optional bucket scope. - Configure your SDK with the displayed HTTPS endpoint and signing region, the access key ID and secret, and AWS Signature Version 4.
- Enable path-style addressing if your SDK would otherwise use AWS bucket hostnames. The service also recognizes configured virtual-host bucket names.
import { S3Client, PutObjectCommand, GetObjectCommand } from "@aws-sdk/client-s3";
const s3 = new S3Client({
endpoint: process.env.HUBFLY_STORAGE_ENDPOINT,
region: process.env.HUBFLY_STORAGE_REGION,
forcePathStyle: true,
credentials: {
accessKeyId: process.env.HUBFLY_STORAGE_ACCESS_KEY_ID,
secretAccessKey: process.env.HUBFLY_STORAGE_SECRET_ACCESS_KEY,
},
});
await s3.send(new PutObjectCommand({
Bucket: "project-assets", Key: "reports/hello.txt",
Body: "Hello", ContentType: "text/plain",
}));
const object = await s3.send(new GetObjectCommand({
Bucket: "project-assets", Key: "reports/hello.txt",
}));Keep the secret on the server. A read-only key can list and read but cannot write, copy, change versioning, or delete.
Supported operations
Paths below use path-style notation. A configured virtual-host request places the bucket in the hostname instead. Supported calls map to the common S3 operations shown here; other S3 features are not implied.
| Method and path | Operation |
|---|---|
GET / | List buckets visible to the key. |
PUT /{bucket}, HEAD /{bucket}, DELETE /{bucket} | Create, check, or delete a bucket. Delete requires an empty bucket. |
GET /{bucket} | List current objects, optionally filtered by prefix and delimiter. |
GET /{bucket}?versioning, PUT /{bucket}?versioning | Read or change bucket versioning state. |
PUT /{bucket}/{key} | Upload an object; with x-amz-copy-source, copy an existing object. |
GET, HEAD, DELETE /{bucket}/{key} | Download, inspect, or delete an object. GET supports a byte Range header. |
POST /{bucket}/{key}?uploads | Initiate multipart upload. |
PUT /{bucket}/{key}?uploadId=…&partNumber=… | Upload or replace a numbered part. |
POST /{bucket}/{key}?uploadId=… | Complete the upload with its part identifiers. |
DELETE /{bucket}/{key}?uploadId=… | Abort a multipart upload and discard staged parts. |
OPTIONS | CORS preflight for configured origins and methods. |
Listing, versions, and ranges
GET /{bucket} accepts prefix, delimiter, max-keys, and continuation-token. A page contains at most 1,000 objects; follow NextContinuationToken while IsTruncated is true. Keys are case-sensitive.
Bucket versioning accepts enabled, suspended, or disabled where the service permits the transition. When enabled, older versions and delete markers may remain. Object GET and DELETE can address a version with versionId. A Range: bytes=0-1023 GET returns a partial response for the first 1,024 bytes.
Multipart uploads
Initiate, PUT each part with its part number and upload ID, then complete with the uploaded parts. If the workflow is abandoned, send the abort request. Staged parts consume storage until completed, aborted, or cleaned up by service policy. Use your SDK’s multipart helper where possible.
Responses and errors
The S3 endpoint returns XML error documents with a code such as AccessDenied, SignatureDoesNotMatch, or NotImplemented, and a request ID in x-amz-request-id. Unknown S3 operations and server-side encryption headers return NotImplemented. Server-side encryption is not available; encrypt sensitive object bodies in your application before upload.
<?xml version="1.0" encoding="UTF-8"?>
<Error>
<Code>AccessDenied</Code>
<Message>The access key is read-only</Message>
<RequestId>req_…</RequestId>
</Error>| Code | What to check |
|---|---|
AccessDenied, SignatureDoesNotMatch | Key state, read/write or bucket scope, signing region, clock, and signed payload. |
NoSuchKey | Exact bucket, key casing, current version, or delete marker. |
BucketAlreadyExists, BucketNotEmpty | Choose an available bucket name or remove remaining objects before deletion. |
QuotaExceeded | Project usage and staged multipart bytes; this can return HTTP 507. |
InvalidRequest, NotImplemented | Request shape or a feature outside the supported operation set. |
Check the signing inputs first