Accounts, The Master Key, Application Keys, and Permissions
As valuable as storing data is, the ability to retrieve it on demand makes it more valuable. Enabling others to access that data directly, but in a secure and limited way, simplifies many uses cases. Backblaze addresses both needs with Account Keys and Application Keys.
The Backblaze B2 Storage Master Application Key
Every Backblaze storage account has a unique email address associated with it, and a unique AccountID. Together, they are used to create a Master Application Key that has complete access to everything in the account. This Master Application Key can create and delete buckets, upload and download files, delete files, and manage Application Keys. The Master Application key must be created on our website. Once it is generated, it is displayed only once (Backblaze does not store this application key), so best practice is to write the Master Application Key down, or store it safely.
A key (Master Application Key or an Application Key) has a ApplicationKeyIdentifier. The Master Application Key always uses the AccountID as its ApplicationKeyIdentifier: the AccountID and the ApplicationKeyIdentifier are identical.
An account has only one Master Application Key. Returning to the Backblaze web site, and displaying the Master Application Key revokes any existing Master Application Key. Please note that regenerating/revoking the Master Key for an account does not affect any existing Application Keys: Application Keys remain valid until they expire, or are explicitly deleted.
The Master Application Key is not a flexible or convenient way to manage access to an account’s data. Best practice is to create this key, and use it only when absolutely required. Otherwise, it should be held in reserve.
Application Keys are far more flexible: they can restrict access to a single bucket or merely some subset files within a bucket, have read-only or write-only permissions, and even expire at a predetermined time. They can even create new application keys (although this capability should be used with care).
An ApplicationKey has a corresponding ApplicationKeyID, which must be used to identify the ApplicationKey. A common error is to use the AccountID instead of the ApplicationKeyId in API calls. The B2 API response contains the correct key identifier. As the V1 API existed prior to ApplicationKeys, the field name in the JSON response is accountId when the field might more appropriately be named applicationKeyId.
What can ApplicationKey permissions do?
- An ApplicationKey may be given a limited lifespan.
- Minimum time 1 second
- Maximum time 10,000 days
- Although a key may be manually revoked before its expiration, its expiration cannot be changed once the key is created.
- Manage Application Keys
- List ApplicationKeys
- Create ApplicationKeys
- ApplicationKeys may be created with any permission set. A key with this capability can always create a key to read/write/list/delete all buckets and keys, giving full access to the account.
- Delete ApplicationKeys
- List ApplicationKeys
- Only keys that are not limited to a single bucket may manage keys
- Limit access to the stored data
- Read-only access: if the file’s access URL is known, it can be downloaded
- Write only access: files may be uploaded
- Delete access: required to erase files from B2 storage
- List Buckets: required to list bucketnames
- The V1 API assumes this permission is present when the ApplicationKey is restricted to a single bucket. Attempting to list buckets without this specific permission will return only the bucket the ApplicationKey is valid on.
- The V2 API requires this permission to list a bucket even if the ApplicationKey is valid only for a single bucket. Additionally, it will only list the single bucket that the ApplicationKey is valid on.
- Restrict access to a single bucket
- A single-bucket ApplicationKey is completely restricted to that bucket
- A single-bucket ApplicationKey cannot create, read, or delete ApplicationKeys
- Restrict access to a file prefix within a bucket
- Only files with a matching prefix may be accessed
- This can only be set with a single-bucket key