S3-Compatible API

The Backblaze B2 Cloud Storage S3-Compatible API does the same thing as the Native API—it allows you to interact with Backblaze B2—but it follows the S3 syntax. With the S3-Compatible API, if your application is already written to use the S3 API, Backblaze B2 will just work, with minimal code changes on your end. The S3-Compatible API provides developers with the following benefits:

• You do not have to learn a new API.
• You can use your existing tools that are written to the S3 API.
• Performance will be just as good, and you’ll get all the benefits of Backblaze B2.

Naming Restrictions

The S3-Compatible API features slightly different restrictions on file and bucket names than the AWS S3 API. Refer to the Buckets and Files page for naming restrictions.

Access Control Lists

The S3-Compatible API features limited support for access control lists (ACLs). Get Object ACL and Get Bucket ACL calls will work as expected. However, object-level ACLs are not supported. For example, a Get Object ACL call returns the ACL for the bucket in which the object is contained.

If a bucket is private, the ACL that is returned for the bucket and any files within the bucket are “private.” If a bucket is public, the ACL that is returned for the bucket and any files within the bucket are “public-read.”

The S3-Compatible API supports the Put Bucket ACL call to change between "private" and “public-read” only. Attempting to put a different value returns an error.

The call succeeds only when the specified ACL matches the ACL of the bucket.

Pre-Signed URLs

The S3-Compatible API supports pre-signed URLs for downloading and uploading. You can generate pre-signed URLs using the AWS CLI, AWS Tools for PowerShell, s3cmd, and AWS SDKs.

The following guides can help you configure these tools:

• AWS Command-Line Interface
• s3cmd
• Native API SDKs
• S3-Compatible SDKs

Server-Side Encryption

The S3-Compatible API supports server-side encryption of data before storing using either Backblaze-managed keys (SSE-B2) or using customer-managed keys (SSE-C). For more information on supported SSE options, click here.

Get Object Tagging

The S3-Compatible API does not fully support object tagging. Therefore, the implementation of Get Object Tagging returns a set of empty tags. This implementation is provided for compatibility with certain integrations.

Copy Object and Tagging

The S3-Compatible API does not fully support object tagging. The x-amz-tagging-directive header is allowed on the Copy Object API, but it will be ignored, no matter the value that you supply. Also, note that the x-amz-tagging header will be explicitly rejected if it is included on the Copy Object (or Put Object) API calls. This implementation is provided for compatibility with certain integrations.

Unsupported Features

The S3-Compatible API does not currently support the following features:

• ACLs
• IAM Roles
• Object Tagging
• Bucket Logging
• Website Configuration
• Lifecycle Rules (This feature is supported by the Backblaze B2 Native API.)
• Browser-based uploads to pre-signed URLs using POST
• Requests that include the following checksum HTTP headers are rejected with a 400 Bad Requestresponse:
  • x-amz-checksum-crc32
  • x-amz-checksum-crc32c
  • x-amz-checksum-sha1
  • x-amz-checksum-sha256
  • x-amz-checksum-algorithm
  • x-amz-checksum-mode