S3 APIs
Intro
The Cubbit S3 Gateway supports most of the AWS S3 RESTful APIs used by the AWS SDKs (like aws-sdk-js, aws-sdk-go, etc), by the official AWS Command Line Interface and by all the S3 compatible clients.
This implies that the aforementioned tools can be used with Cubbit simply by configuring them to use the right endpoint, i.e. https://s3.cubbit.eu. For example, in this documentation, you can find instructions on how to setup the AWS CLI.
The following sections describe broadly what features are currently supported and how closely they reflect the original AWS S3 specification. The final section gives a detailed view of what API methods are supported.
Bucket management
Creating and deleting new buckets is supported, along with listing their content.
Object management
Uploading, downloading, copying, and deleting objects are fully supported operations.
Multipart Upload
Multipart Uploads are fully supported. More information about the multipart upload can be found here.
Versioning
Versioning can be activated on a bucket and can be suspended. All operations related to versioned objects, like creating new versions, listing, or deleting them are supported. More information on bucket versioning can be found here.
Object Lock
The Object Lock feature is fully supported. The following table summarizes the various lock methods.
| Lock type | Mode | Support |
|---|---|---|
| Legal Hold | - | Yes |
| Object Retention | COMPLIANCE | Yes |
| Object Retention | GOVERNANCE | Yes |
ACL
ACL APIs are supported.
The grantee may be one of the following:
- a user (by their ID or their email)
- a predefined group
The supported predefined groups are:
- AllUsers
- AuthenticatedUsers
It should also be noted that:
- read and write operations are not yet supported in a public-read or public-read-write scenario
- the implementation of these groups might slightly change in the future
The following canned ACLs are allowed:
- private
- public-read (with the aforementioned limitations)
- public-read-write (with the aforementioned limitations)
- authenticated-read
- bucket-owner-read
- bucket-owner-full-control
More information can be found here.
Lifecycle Configuration
The Lifecycle Configuration feature is partially supported.
A single configuration rule is allowed. The only configuration rule supported is the NoncurrentVersionExpiration with no filters.
More information can be found here.
Object Tagging
We support the core Object Tagging APIs for managing tags on individual S3 objects:
PutObjectTagging: Assign or replace the complete tags set on an existing object.GetObjectTagging: Retrieve all tags associated with a specified object.DeleteObjectTagging: Remove all tags from a specified object.
We also preserve tags when copying objects using the CopyObject API.
Unsupported Tagging Features
Specific tagging capabilities in ancillary APIs are not yet supported:
- ⚠️ Tagging at Upload Time: You cannot add tags inline during
PutObjectorCreateMultipartUploadrequests. - ⚠️ Tag Count in Retrieval: The
GetObjectresponse does not include thex-amz-tagging-count header. - ⚠️ Tag Overwrite on Copy: You cannot override or replace tags via
CopyObject. Only tag preservation is supported.
note
Some legacy buckets created before object tagging was available may not support tagging operations at all. If you happen to encounter errors, please make sure that the target bucket has tagging enabled.
Bucket Tagging
Not supported.
Object Lifecycle
Not supported.
Request Headers
The Cubbit S3 Gateway accepts the request headers summarized below. The table lists the significant S3 request headers and whether the gateway evaluates them. A header marked No is accepted without error but is not evaluated: its effect is not applied by the gateway. Authentication and signing headers (such as Authorization and x-amz-date) are handled as part of normal request processing and are not listed. Support for conditional requests is targeted for early 2027; the exact release date is subject to change.
warning
Some of the headers below are used by S3 clients to protect data: conditional writes, checksums, and client-side encryption keys are not enforced yet. Until support is available, do not rely on them to prevent overwrites, to verify integrity, or to encrypt objects with your own key.
| Family | Request header | Applies to | Evaluated | Notes |
|---|---|---|---|---|
| Metadata | Content-Type | CopyObject, CreateMultipartUpload, PutObject | Yes | Stored as object metadata; on CopyObject, only with x-amz-metadata-directive: REPLACE. |
| Metadata | Content-Disposition | CopyObject, CreateMultipartUpload, PutObject | Yes | Stored as object metadata; on CopyObject, only with x-amz-metadata-directive: REPLACE. |
| Metadata | Content-Encoding | CopyObject, CreateMultipartUpload, PutObject | Yes | Stored as object metadata; on CopyObject, only with x-amz-metadata-directive: REPLACE. |
| Metadata | Cache-Control | CopyObject, CreateMultipartUpload, PutObject | Yes | Stored as object metadata; on CopyObject, only with x-amz-metadata-directive: REPLACE. |
| Metadata | x-amz-meta-* | CopyObject, CreateMultipartUpload, PutObject | Yes | Stored with the object; a total size limit applies; on CopyObject, only with x-amz-metadata-directive: REPLACE. |
| Metadata | Content-Language | CopyObject, CreateMultipartUpload, PutObject | No | Not stored with the object. |
| Metadata | Expires | CopyObject, CreateMultipartUpload, PutObject | No | Not stored with the object. |
| Access Control | x-amz-acl | CreateBucket, CopyObject, CreateMultipartUpload, PutBucketAcl, PutObject, PutObjectAcl | Yes | Validated; invalid canned ACLs are rejected. |
| Access Control | x-amz-grant-read | CreateBucket, CopyObject, CreateMultipartUpload, PutBucketAcl, PutObject, PutObjectAcl | Yes | |
| Access Control | x-amz-grant-read-acp | CreateBucket, CopyObject, CreateMultipartUpload, PutBucketAcl, PutObject, PutObjectAcl | Yes | |
| Access Control | x-amz-grant-write | CreateBucket, PutBucketAcl, PutObjectAcl | Yes | Ignored when writing object data (PutObject, CopyObject, CreateMultipartUpload); honored on bucket ACLs. On object ACLs (PutObjectAcl) the grant is stored but never evaluated by object authorization. |
| Access Control | x-amz-grant-write-acp | CreateBucket, CopyObject, CreateMultipartUpload, PutBucketAcl, PutObject, PutObjectAcl | Yes | |
| Access Control | x-amz-grant-full-control | CreateBucket, CopyObject, CreateMultipartUpload, PutBucketAcl, PutObject, PutObjectAcl | Yes | |
| Access Control | x-amz-expected-bucket-owner | Most bucket and object operations | Yes | A mismatch returns Access Denied. |
| Access Control | x-amz-source-expected-bucket-owner | CopyObject, UploadPartCopy | No | The source bucket owner is not checked. |
| Access Control | x-amz-object-ownership | CreateBucket | Yes | Validated; unknown values are rejected. |
| Object Lock | x-amz-object-lock-mode | CopyObject, CreateMultipartUpload, PutObject | Yes | Enforced. |
| Object Lock | x-amz-object-lock-retain-until-date | CopyObject, CreateMultipartUpload, PutObject | Yes | Enforced. |
| Object Lock | x-amz-object-lock-legal-hold | CopyObject, CreateMultipartUpload, PutObject | Yes | Enforced. |
| Object Lock | x-amz-bypass-governance-retention | DeleteObject, DeleteObjects, PutObjectRetention | Yes | Enforced. |
| Object Lock | x-amz-bucket-object-lock-enabled | CreateBucket | Yes | Enforced. |
| Object Lock | x-amz-bucket-object-lock-token | PutObjectLockConfiguration | No | Not evaluated. |
| Copy | x-amz-copy-source | CopyObject, UploadPartCopy | Yes | Required to identify the source object. |
| Copy | x-amz-copy-source-range | UploadPartCopy | Yes | Enforced. |
| Copy | x-amz-metadata-directive | CopyObject | Yes | COPY and REPLACE are honored. |
| Storage | x-amz-storage-class | CopyObject, CreateMultipartUpload, PutObject | Yes | Validated; invalid storage classes are rejected. |
| Misc | Range | GetObject, HeadObject | Yes | Byte-range requests are honored. |
| Misc | x-amz-request-payer | Most bucket and object operations | No | No effect; Requester Pays is not supported. |
| Misc | x-amz-mfa | DeleteObject, DeleteObjects, PutBucketVersioning | No | No effect; the bucket's Multi-Factor Authentication (MFA) Delete setting is enabled through the PutBucketVersioning request body and reported by GetBucketVersioning, but it is never enforced on delete operations. |
| Misc | x-amz-website-redirect-location | CopyObject, CreateMultipartUpload, PutObject | No | Not stored. |
| Misc | x-amz-optional-object-attributes | ListObjectVersions, ListObjects, ListObjectsV2 | No | Not returned. |
| Conditional | If-Match | CompleteMultipartUpload, DeleteObject, DeleteObjects, GetObject, HeadObject, PutObject | No | Not evaluated; no 412 Precondition Failed is returned. |
| Conditional | If-None-Match | CompleteMultipartUpload, GetObject, HeadObject, PutObject | No | Not evaluated; no 412 Precondition Failed or 304 Not Modified is returned. |
| Conditional | If-Modified-Since | GetObject, HeadObject | No | Not evaluated; no 304 Not Modified is returned. |
| Conditional | If-Unmodified-Since | GetObject, HeadObject | No | Not evaluated; no 412 Precondition Failed is returned. |
| Conditional | x-amz-copy-source-if-match | CopyObject, UploadPartCopy | No | Not evaluated; the copy is performed unconditionally. |
| Conditional | x-amz-copy-source-if-none-match | CopyObject, UploadPartCopy | No | Not evaluated; the copy is performed unconditionally. |
| Conditional | x-amz-copy-source-if-modified-since | CopyObject, UploadPartCopy | No | Not evaluated; the copy is performed unconditionally. |
| Conditional | x-amz-copy-source-if-unmodified-since | CopyObject, UploadPartCopy | No | Not evaluated; the copy is performed unconditionally. |
| Server-Side Encryption | x-amz-server-side-encryption | CopyObject, CreateMultipartUpload, PutObject | No | Not applied; objects are stored with the platform's default encryption. |
| Server-Side Encryption | x-amz-server-side-encryption-aws-kms-key-id | CopyObject, CreateMultipartUpload, PutObject | No | Not applied. |
| Server-Side Encryption | x-amz-server-side-encryption-context | CopyObject, CreateMultipartUpload, PutObject | No | Not applied. |
| Server-Side Encryption | x-amz-server-side-encryption-bucket-key-enabled | CopyObject, CreateMultipartUpload, PutObject | No | Not applied. |
| Server-Side Encryption | x-amz-server-side-encryption-customer-algorithm | CompleteMultipartUpload, CopyObject, CreateMultipartUpload, GetObject, HeadObject, ListParts, PutObject, UploadPart, UploadPartCopy | No | The client-provided key is never used. |
| Server-Side Encryption | x-amz-server-side-encryption-customer-key | CompleteMultipartUpload, CopyObject, CreateMultipartUpload, GetObject, HeadObject, ListParts, PutObject, UploadPart, UploadPartCopy | No | The client-provided key is never used. |
| Server-Side Encryption | x-amz-server-side-encryption-customer-key-md5 | CompleteMultipartUpload, CopyObject, CreateMultipartUpload, GetObject, HeadObject, ListParts, PutObject, UploadPart, UploadPartCopy | No | The client-provided key is never used. |
| Server-Side Encryption | x-amz-copy-source-server-side-encryption-customer-algorithm | CopyObject, UploadPartCopy | No | The source encryption key is never used. |
| Server-Side Encryption | x-amz-copy-source-server-side-encryption-customer-key | CopyObject, UploadPartCopy | No | The source encryption key is never used. |
| Server-Side Encryption | x-amz-copy-source-server-side-encryption-customer-key-md5 | CopyObject, UploadPartCopy | No | The source encryption key is never used. |
| Checksums | x-amz-checksum-crc32 | CompleteMultipartUpload, PutObject, UploadPart | No | The checksum is not verified. |
| Checksums | x-amz-checksum-crc32c | CompleteMultipartUpload, PutObject, UploadPart | No | The checksum is not verified. |
| Checksums | x-amz-checksum-crc64nvme | CompleteMultipartUpload, PutObject, UploadPart | No | The checksum is not verified. |
| Checksums | x-amz-checksum-sha1 | CompleteMultipartUpload, PutObject, UploadPart | No | The checksum is not verified. |
| Checksums | x-amz-checksum-sha256 | CompleteMultipartUpload, PutObject, UploadPart | No | The checksum is not verified. |
| Checksums | x-amz-checksum-sha512 | CompleteMultipartUpload, PutObject, UploadPart | No | The checksum is not verified. |
| Checksums | x-amz-checksum-md5 | CompleteMultipartUpload, PutObject, UploadPart | No | The checksum is not verified. |
| Checksums | x-amz-checksum-xxhash64 | CompleteMultipartUpload, PutObject, UploadPart | No | The checksum is not verified. |
| Checksums | x-amz-checksum-xxhash3 | CompleteMultipartUpload, PutObject, UploadPart | No | The checksum is not verified. |
| Checksums | x-amz-checksum-xxhash128 | CompleteMultipartUpload, PutObject, UploadPart | No | The checksum is not verified. |
| Checksums | x-amz-checksum-algorithm | CopyObject, CreateMultipartUpload | No | Not applied. |
| Checksums | x-amz-sdk-checksum-algorithm | Most write operations, including DeleteObjects and bucket configuration requests | No | Not applied. |
| Checksums | x-amz-checksum-mode | GetObject, HeadObject | No | Checksums are not included in the response. |
| Checksums | x-amz-trailer | PutObject, UploadPart | No | Trailers are discarded. |
| Checksums | Content-MD5 | Most object and bucket operations | No | Only used as part of the Signature Version 2 (SigV2) signature; it is never verified against the payload. |
| Object Tagging | x-amz-tagging | CopyObject, CreateMultipartUpload, PutObject | No | Tags are not applied. See Object Tagging. |
| Object Tagging | x-amz-tagging-directive | CopyObject | No | Not applied. See Object Tagging. |
API Compatibility Table
| Method | Support | Notes |
|---|---|---|
| AbortMultipartUpload | Yes | |
| CompleteMultipartUpload | Yes | |
| CopyObject | Yes | |
| CreateBucket | Yes | |
| CreateMultipartUpload | Yes | |
| DeleteBucket | Yes | |
| DeleteBucketAnalyticsConfiguration | No | |
| DeleteBucketCors | No | |
| DeleteBucketEncryption | No | |
| DeleteBucketIntelligentTieringConfiguration | No | |
| DeleteBucketInventoryConfiguration | No | |
| DeleteBucketLifecycle | Yes | |
| DeleteBucketMetricsConfiguration | No | |
| DeleteBucketOwnershipControls | Yes | |
| DeleteBucketPolicy | No | |
| DeleteBucketReplication | No | |
| DeleteBucketTagging | No | |
| DeleteBucketWebsite | No | |
| DeleteObject | Yes | |
| DeleteObjects | Yes | |
| DeleteObjectTagging | Yes | May not be available for some buckets |
| DeletePublicAccessBlock | No | |
| GetBucketAccelerateConfiguration | No | |
| GetBucketAcl | Yes | |
| GetBucketAnalyticsConfiguration | No | |
| GetBucketCors | No | |
| GetBucketEncryption | No | |
| GetBucketIntelligentTieringConfiguration | No | |
| GetBucketInventoryConfiguration | No | |
| GetBucketLifecycle | No | |
| GetBucketLifecycleConfiguration | Yes | NoncurrentVersionExpiration only |
| GetBucketLocation | Yes | |
| GetBucketLogging | No | |
| GetBucketMetricsConfiguration | No | |
| GetBucketNotification | No | |
| GetBucketNotificationConfiguration | No | |
| GetBucketOwnershipControls | Yes | |
| GetBucketPolicy | No | |
| GetBucketPolicyStatus | No | |
| GetBucketReplication | No | |
| GetBucketRequestPayment | No | |
| GetBucketTagging | No | |
| GetBucketVersioning | Yes | |
| GetBucketWebsite | No | |
| GetObject | Yes | |
| GetObjectAcl | Yes | |
| GetObjectAttributes | No | |
| GetObjectLegalHold | Yes | |
| GetObjectLockConfiguration | Yes | |
| GetObjectRetention | Yes | |
| GetObjectTagging | Yes | May not be available for some buckets |
| GetObjectTorrent | No | |
| GetPublicAccessBlock | No | |
| HeadBucket | Yes | |
| HeadObject | Yes | |
| ListBucketAnalyticsConfigurations | No | |
| ListBucketIntelligentTieringConfigurations | No | |
| ListBucketInventoryConfigurations | No | |
| ListBucketMetricsConfigurations | No | |
| ListBuckets | Yes | |
| ListMultipartUploads | Yes | |
| ListObjects | Yes | |
| ListObjectsV2 | Yes | |
| ListObjectVersions | Yes | |
| ListParts | Yes | |
| PutBucketAccelerateConfiguration | No | |
| PutBucketAcl | Yes | |
| PutBucketAnalyticsConfiguration | No | |
| PutBucketCors | No | |
| PutBucketEncryption | No | |
| PutBucketIntelligentTieringConfiguration | No | |
| PutBucketInventoryConfiguration | No | |
| PutBucketLifecycle | No | |
| PutBucketLifecycleConfiguration | Yes | NoncurrentVersionExpiration only |
| PutBucketLogging | No | |
| PutBucketMetricsConfiguration | No | |
| PutBucketNotification | No | |
| PutBucketNotificationConfiguration | No | |
| PutBucketOwnershipControls | Yes | |
| PutBucketPolicy | No | |
| PutBucketReplication | No | |
| PutBucketRequestPayment | No | |
| PutBucketTagging | No | |
| PutBucketVersioning | Yes | |
| PutBucketWebsite | No | |
| PutObject | Yes | |
| PutObjectAcl | Yes | |
| PutObjectLegalHold | Yes | |
| PutObjectLockConfiguration | Yes | |
| PutObjectRetention | Yes | |
| PutObjectTagging | Yes | May not be available for some buckets |
| PutPublicAccessBlock | No | |
| RestoreObject | No | |
| SelectObjectContent | No | |
| UploadPart | Yes | |
| UploadPartCopy | Yes | |
| WriteGetObjectResponse | No |