The Backblaze S3 Compatible API easily integrates with your existing data management tools and S3 gateways. Backblaze B2 Cloud Storage is ⅕ the price of AWS S3 so you can quickly integrate B2 and see dramatic savings on your cloud storage bill.

If you aren’t currently a Backblaze B2 user you can start an account today and get your first 10GBs of storage free.

Start Now

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.

Tutorial

Follow our tutorial to get started with the Backblaze S3 Compatible API using Python: Backblaze B2 Quick Start: Using Python With the Backblaze S3 Compatible API

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 (DELETE)
Complete Multipart Upload (POST)
Copy Object (PUT)
Create Bucket (PUT)
Create Multipart Upload (POST)
Delete Bucket
Delete Bucket Cors
Delete Bucket Encryption
Delete Object
Delete Objects (POST)
Get Bucket ACL
Get Bucket Cors
Get Bucket Encryption
Get Bucket Location
Get Bucket Versioning
Get Object
Get Object ACL
Get Object Legal Hold
Get Object Lock Configuration
Get Object Retention
Head Bucket
Head Object
List Buckets (GET)
List Multipart Uploads (GET)
List Object Versions (GET)
List Objects (GET)
List Objects V2 (GET)
List Parts (GET)
Put Bucket ACL
Put Bucket Cors
Put Bucket Encryption
Put Object
Put Object ACL
Put Object Legal Hold
Put Object Lock Configuration
Put Object Retention
Upload Part (PUT)
Upload Part Copy (PUT)

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 "private" and “public-read” only. Attempting to put a different value will return an error.

The Put Object ACL call only supports the same canned ACL values mentioned previously. The call will succeed only when specified ACL matches the ACL of the bucket.

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 and Delete Objects 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.

Application Key Capabilities

As with the B2 Native API, the capabilities of an application key give you access to the S3 Compatible API. These are the capabilities for the S3 Compatible API:

listBuckets

Lets the client list the buckets in the account or check if they exist.

In an application key restricted to one bucket, listing the buckets requires the listAllBucketNames capability.

Provides access to these APIs:

List Buckets
Head Bucket

listAllBucketNames

Lets the client list the buckets in the account even if the application key is restricted to one buckets.

Provides access to this API:

List Buckets

readBuckets

Lets the client read additional information about a bucket like ACLs, Location, and Versioning.

Provides access to these APIs:

Get Bucket ACL
Get Bucket Cors
Get Bucket Location
Get Bucket Versioning

writeBuckets

Lets the client create new buckets in the account, and update the bucket type, bucket info, and lifecycle rules for a bucket.

Writing buckets is not allowed for application keys restricted to a bucket.

Provides access to these APIs:

Create Bucket
Delete Bucket Cors
Put Bucket ACL
Put Bucket Cors
Put Bucket Versioning
Put Object ACL

deleteBuckets

Lets the client delete any bucket in the account.

Deleting buckets is not allowed for application keys restricted to a bucket.

Provides access to this API:

Delete Bucket

readBucketEncryption

Lets the client read the default encryption settings on a bucket.

Provides access to this API:

Get Bucket Encryption

writeBucketEncryption

Lets the client enable or disable default encryption on a bucket.

Provides access to these APIs:

Delete Bucket Encryption
Put Bucket Encryption

readBucketRetentions

Lets the client read the object lock configuration on a bucket.

Provides access to this API:

Get Object Lock Configuration

writeBucketRetentions

Lets the client enable object lock or update the default lock mode and period on a bucket.

Lets the client have additional access in the Create Bucket API to enable object lock during creation.

Provides access to this API:

Put Object Lock Configuration

listFiles

Lets the client list metadata for their objects. Metadata includes the file name, file id, file info, size, content type, etc.

For application keys restricted to a bucket, only files in that bucket can be listed.

For application keys restricted to a file name prefix, a matching prefix must be included in the list request. You can supply the same prefix as in the application key, or a more restrictive one.

Provides access to these APIs:

List Multipart Uploads
List Objects
List Objects V2
List Object Versions

readFiles

Lets the client see the metadata for files, and download their contents. Metadata includes the file name, file id, file info, size, content type, etc.

For application keys restricted to a bucket, only files in that bucket can be downloaded.

For application keys restricted to a file name prefix, only files whose name starts with that prefix can be downloaded.

Provides access to these APIs:

Copy Object
Get Object
Get Object ACL
Head Object

writeFiles

Lets clients upload files to B2, including both regular files and large files.

For application keys restricted to a bucket, files can only be uploaded to that bucket.

For application keys restricted to a file name prefix, only files whose name starts with that prefix can be uploaded.

Provides access to these APIs:

Abort Multipart Upload
Complete Multipart Upload
Copy Object
Create Multipart Upload
List Parts
Put Object
Put Object ACL
Upload Part

deleteFiles

Lets clients delete files.

For application keys restricted to a bucket, only files in that bucket can be deleted.

For application keys restricted to a file name prefix, only files whose name starts with that prefix can be deleted.

Provides access to these APIs:

Delete Object
Delete Objects

readFileRetentions

Lets clients see the Object Lock settings (mode and expiration) on an object.

These objects must be located in a bucket that has Object Lock enabled.

Provides access to this API:

Get Object Retention

writeFileRetentions

Lets clients update the Object Lock settings (mode and expiration) on an object.

These objects must be located in a bucket that has Object Lock enabled.

Provides access to this API:

Put Object Retention

bypassGovernance

Lets clients delete governance mode-locked files. Also allows governance mode expiration to be shortened and to switch governance mode to compliance mode.

Used in these APIs:

Delete Object
Delete Objects
Put Object Retention

readFileLegalHolds

Lets clients see the Object Lock settings (legal hold status) of an object.

These objects must be located in a bucket that has Object Lock enabled.

Provides access to this API:

Get Object Legal Hold

writeFileLegalHolds

Lets clients update the Object Lock settings (legal hold status) of an object.

These objects must be located in a bucket that has Object Lock enabled.

Provides access to this API:

Put Object Legal Hold

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-east-005.backblazeb2.com

https://s3.us-east-005.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.

Object Lock (Immutability)

The S3 Compatible API supports a complete set of Object Lock calls and capabilities: compliance and governance lock modes, retention periods, legal hold, and default bucket retention settings. If you have specific questions regarding Object Lock support, please refer to our knowledgebase article here.

To enable Object Lock on an existing S3 Compatible bucket, add the x-amz-bucket-object-lock-token header with a value of 1 to the S3 Put Object Lock Configuration API call.

Server-Side Encryption

The S3 Compatible API supports server-side encryption of data before storing on disk using either Backblaze-managed keys (SSE-B2) or using customer-managed keys (SSE-C). Please see Server-Side Encryption for more information on supported SSE options.

Cross-Origin Resource Sharing (CORS)

There are a few key differences in our implementation of CORS support in the S3 Compatible API that are noted here:

AllowedOrigin

An empty value (ex. <AllowedOrigin></AllowedOrigin>) will be rejected and return status code 400 with the message, “illegal empty string in allowedOrigins.”

AllowedMethod

Duplicate elements of the same method will be aggregated on GetBucketCors calls

MaxAgeSeconds

The S3 Compatible API will accept a range of [0, 86400]

XML input size

The size limit for CORS rules XML input is 100 KB

If you plan on using CORS for both the B2 Native API and S3 Compatible API, please see our CORS documentation for expected behavior and differences.

Get Object Tagging

Our implementation of Get Object Taggingis minimal and always returns a set of empty tags, as we do not fully support Object Tagging. This implementation is provided for compatibility with certain integrations.

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 Tagging
Bucket Logging
Website configuration
Lifecycle Rules (supported by the Backblaze B2 Native API)
Requests which include the x-amz-sdk-checksum-algorithm HTTP header (these will be rejected with HTTP status 400)

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.

Feedback

Have a request or idea for the Backblaze S3 Compatible API? Please feel free to contact us at b2feedback@backblaze.com.