S3 Compatible API

The Backblaze S3 Compatible API adds a new API to allow existing S3 integrations and SDKs to easily integrate with Backblaze B2 Cloud Storage. This documentation will serve as a resource for developers and end-users to distinguish the differences between the S3 Compatible API for Backblaze B2 and the Amazon S3 API. If you’re looking to get started with the S3 Compatible API, please refer to our Getting Started guide here.

Authentication

The Backblaze S3 Compatible API only supports v4 signatures for authentication and does not support v2 signatures at this time. To learn more about S3 authentication, see this article.

Supported Calls

The Backblaze S3 Compatible API returns calls in the same way the AWS S3 API does. Note that this may vary slightly from AWS S3 API documentation - this difference is expected based on the AWS S3 API. Here are the calls that are supported:

  • Abort Multipart Upload
  • Complete Multipart Upload
  • Create Bucket
  • Delete Bucket
  • Delete Multiple Objects
  • Delete Object
  • Get Bucket ACL
  • Get Bucket Location
  • Get Bucket Object Versions
  • Get Object
  • Get Object ACL
  • Head Bucket
  • Head Object
  • Initiate Multipart Upload
  • List Buckets
  • List Multipart Uploads
  • List Objects v2
  • List Parts
  • Put Bucket ACL
  • Put Object
  • Put Object Copy
  • Upload Part
  • Upload Part Copy

ACLs

The Backblaze S3 Compatible API features limited support for ACLs (Access Control Lists). 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 the object is contained in.

If a Bucket is Private, the ACL returned for the Bucket and any files within the bucket will be “PRIVATE”. If a Bucket is Public, the ACL returned for the Bucket and any files within the bucket will be “PUBLIC_READ”.

The S3 Compatible API supports the Put Bucket ACL call to change between the Get Object ACL and Get Bucket ACL calls only. Attempting to put a different value will return an error.

Naming Restrictions

The Backblaze S3 Compatible API features slightly different restrictions on file and Bucket names than the AWS S3 API. Please refer to the Buckets and Files page for naming restrictions.

Access Key ID and Secret Access Key

For the purposes of terminology, the Application Key and Application Key ID are the equivalent of the Secret Access Key and Access Key ID respectively. For more information about App Keys, please see our documentation here.

Application Key Restrictions

The automatically created Master Application Key is not supported in the Backblaze S3 Compatible API - only Application Keys that are manually created in the Backblaze Web UI or via the Backblaze B2 Native API can be used to authenticate the Backblaze S3 Compatible API.

If an Application Key is restricted to a bucket, the listAllBucketNames permission is required for compatibility with SDKs and integrations. The listAllBucketNames permission can be enabled upon creation in the web UI or using the b2_create_key API call.

The Delete Object call may require that the App Key have both the writeFiles and deleteFiles capabilities. The writeFiles permission is necessary when deleting by name and the deleteFiles permission is required when deleting a specific version. As a general rule, both the writeFiles and deleteFiles permissions should be associated with the key used for deleting files in the S3 Compatible API.

The Backblaze S3 Compatible API does not support unauthenticated ListObject calls on Public Buckets.

Versioning

Buckets in Backblaze B2 Cloud Storage are versioned by default. Because Buckets are versioned, when a file is deleted by referencing the name only the most recent version of that file will be deleted and older versions of the file will continue to exist in the Bucket. Older versions of files can be deleted automatically by using the Backblaze Lifecycle Rules. Lifecycle Rules are currently only available through the Backblaze Web UI and the Backblaze B2 Native API.

Endpoints/URLs

The format for endpoints for the Backblaze S3 Compatible API:

https://s3.<region>.backblazeb2.com

The Backblaze S3 Compatible API endpoints only accept connections over HTTPS. Non-secure connections will be rejected. The AWS SDKs and most integrations only require an Endpoint URL like the above (without the bucket name included).

If making the HTTP calls directly, the Backblaze S3 Compatible API supports specifying the bucket name in the hostname of the URL or in the path section of the URL. Both URLs below are valid examples of an endpoint calling a bucket:

https://bucketname.s3.us-west-001.backblazeb2.com
https://s3.us-west-001.backblazeb2.com/bucketname

Pre-signed URLs

The Backblaze S3 Compatible API supports pre-signed URLs for downloading and uploading. The pre-signed URLs can be generated in a number of ways including the AWS CLI, AWS Tools for PowerShell, and AWS SDKs.

SDKs

The Backblaze S3 Compatible API can be used with existing AWS SDKs. Guides on how to configure the AWS SDKs can be found in the knowledge base:

Unsupported Features

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

  • ACLs (see above)
  • IAM roles
  • Object Locks
  • Object Tagging
  • Bucket Logging
  • Legal Hold
  • Website configuration
  • Lifecycle Rules (supported by the Backblaze B2 Native API)
  • Server-side Encryption

Successive Calls

When uploading multiple versions of the same file within the same second, the possibility exists that the processing of these versions may not be in order. Backblaze recommends delaying uploads of multiple versions of the same file by at least one second to avoid this situation.

Similarly, when hiding a file within the same second as uploading that file, it is possible that the file may not actually be hidden. To avoid such a situation, please delay such calls on the same file by at least one second.

In Development

Several features are on our roadmap to be included in a future release for the Backblaze S3 Compatible API. Once new features are supported more information will be added to this page.

  • Minimal support for Get/Put BucketVersioning
  • CORS

Feedback

Have a request or idea for the Backblaze S3 Compatible API? Please feel free to contact us at [email protected].