Source Code Bundles
S3 Compatible API
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. If you’re looking to get started with the S3 Compatible API, please refer to our Getting Started guide.
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.
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 ACL
- Put Object Copy
- Upload Part
- Upload Part Copy
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.
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.
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
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.
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.
The format for endpoints for the Backblaze S3 Compatible API:
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:
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 subset of Object Lock calls and capabilities. The scope of support for Object Lock calls and headers is centered on support for Immutability in Veeam Backup & Replication (v10). If you have specific questions regarding Object Lock support, please refer to our knowledgebase article here.
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:
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
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.
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
Have a request or idea for the Backblaze S3 Compatible API? Please feel free to contact us at [email protected].