Application keys control access to your B2 account. You can get the master application key for your account from the B2 Cloud Storage Buckets page on the Backblaze web site.

The master application key for your account has complete access, but will become invalid if you generate a new one. Application keys can be useful because they continue to work even when you change the master application key, and because the application key can be deleted to stop access using it without disrupting other users.

Master Application Key: This is the first key you have access to, it is available on the web application. This key has all capabilities, access to all buckets, and has no file prefix restrictions or expiration.

Application Key(s) [non-master]: These are other keys created by you and can be limited to a bucket, with a specific file prefix, have limited capabilities and can expire.

If you are using a B2 integration partner, please confirm that their app supports application keys.

When using application keys, it is a good idea to create a key with just enough capabilities. You can useb2_create_key to create an application key with specific capabilities. If you want, it can be limited to a single storage bucket, or even to certain files within a bucket. For example, you can create a key that can only upload files to a single bucket.

It is fine to make a lot of application keys. If you are creating a cell phone app and want to make a key for each of your customers, that's fine. The current limit lets you create 100 million keys per account. (Talk to us if you need more.)

The API calls related to application keys are:

b2_authorize_account - uses an application key to generate an authorization token
b2_create_key - creates a new application key for your account
b2_delete_key - deletes one application key
b2_list_keys - lists all application keys in your account

Using Application Keys

The sequence of actions to access B2 is:

Log into your account, and create the master application key for the account. This master application key is good until a new one is created. Creating a new master application key invalidates the old one.
Use the master application key with b2_authorize_account to create an authorization token that is capable of creating application keys.
Create an application key with the capabilities you require to access B2. This key is good indefinitely, unless you set an expiration time.
Use the new application key to get an authorization token that can be use to access the B2 APIs. Authorization tokens are only good for 24 hours. You can use the application key to make new authorization tokens as they expire.

Each application key grants access to different capabilities in B2. The authorization token you get when you use an application key is limited to the capabilities of the application key.

Managing Application Keys

You can create new keys with b2_create_key, list all of the existing keys with b2_list_keys, and delete keys with b2_delete_key.

NOTE: It takes a couple minutes for some changes to keys to take effect. When you generate a new master application key, it takes time for the old one to be invalidated, and for the new one to become active. When you delete an application key before its expiration time, it takes time for the deletion to take effect. You can expect these changes to take effect in under 5 minutes.

When you create a new application key, the response contains the actual key string, which looks like: N2Zug0evLcHDlh_L0Z0AJhiGGdY. This is the only time you will get the key string. If you lose it, you will need to create a new application key. There is no way to retrieve the key string for an existing key.

You can assign a name to a new application key, but the name is only for your use. It is not possible to look up a key by name. There is no requirement that names are unique.

Application keys can have expiration times. Once a key expires, it ceases to exist. Expired keys can no longer be used to generate auth tokens, and will no longer be listed by b2_list_keys.

Capabilities

Each application key is associated with a set of capabilities, and each of those capabilities give you access to some of the B2 APIs. These are all of the capabilities, and their associated APIs:

listKeys

Lets the client enumerate the application keys in an account, and see their metadata. The metadata for a key includes everything except the secret application key string itself.

Provides access to these APIs:

b2_list_keys

writeKeys

Lets the client create new application keys, and does not impose any restrictions on what those keys can do. Giving out writeKeys capability gives out full access to the B2 account!

Provides access to these APIs:

b2_create_key

deleteKeys

Lets the client delete any application key that belongs to the account.

Provides access to these APIs:

b2_delete_key

listBuckets

Lets the client list the buckets in the account, and their metadata. The metadata includes the bucket ID, bucket name, bucket type, bucket info, CORS rules, and lifecycle rules.

In an application key restricted to one bucket, listing buckets is only allowed if you provide the bucket's name or ID in the b2_list_buckets request.

Provides access to these APIs:

b2_list_buckets

listAllBucketNames

Lets the client list the names and IDs of all buckets in the account, even with application keys that are restricted to a bucket.

This capability provides access only to the S3 Compatible API List Buckets, as there is currently no B2 Native API that lists only bucket names and IDs.

readBuckets

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

This capability provides access only to the relevant S3 Compatible API, as there is currently no B2 Native API which provides such information.

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:

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 these APIs:

b2_delete_bucket

readBucketRetentions

Lets the client see whether a bucket has Object Lock enabled.

Also allows clients to see the default lock mode and period (if configured) on a bucket that has Object Lock enabled.

Used in these APIs:

writeBucketRetentions

Lets the client create a bucket that has Object Lock enabled.

Also allows clients to update the default lock mode and period on a bucket that has Object Lock enabled.

Used in these APIs:

readBucketEncryption

Lets the client see default encryption settings on a bucket.

Used in these APIs:

writeBucketEncryption

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

Used in these APIs:

listFiles

Lets the client list files and their metadata. 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:

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:

shareFiles

Lets the client create authorization tokens for downloading files.

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

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

Provides access to these APIs:

b2_get_download_authorization

writeFiles

Lets the client upload files to B2, including both regular files and large files. To support large file uploads, all of the APIs involved in uploading large files are allowed.

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:

deleteFiles

Lets the client 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:

b2_delete_file_version

readFileLegalHolds

Lets the client see the Object Lock legal hold status on a file.

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

Used in these APIs:

writeFileLegalHolds

Lets the client update the Object Lock legal hold status on a file.

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

Used in these APIs:

readFileRetentions

Lets the client see the Object Lock retention settings (mode and expiration) on a file.

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

Used in these APIs:

writeFileRetentions

Lets the client update the Object Lock retention settings (mode and expiration) on a file.

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

Used in these APIs:

bypassGovernance

Lets the client 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:

readBucketReplications

Allows the client to read—but not change—bucket replication information. For more information, see Cloud Replication.

Used in these APIs:

writeBucketReplications

Lets the client write bucket replication information. See here for more details on Cloud Replication.

Used in these APIs:

Bucket Restriction

An application key can be restricted to one bucket. All access to all other buckets will be unauthorized, except for application keys with the listAllBucketNames capability, which can still see all of the bucket names in the account.

When making a b2_list_buckets request with a key restricted to one bucket, you must include the bucket's ID (or name) in the request, and thereby request a list of just that one bucket. Asking for a list of all buckets is unauthorized with a bucket-restricted key.

Application keys that are restricted to a bucket can only have these capabilities:

listAllBucketNames
listBuckets
readBuckets
readBucketEncryption
writeBucketEncryption
readBucketRetentions
writeBucketRetentions
listFiles
readFiles
shareFiles
writeFiles
deleteFiles
readFileLegalHolds
writeFileLegalHolds
readFileRetentions
writeFileRetentions
bypassGovernance
readBucketReplications
writeBucketReplications

Application keys can also be restricted to the files in a bucket matching a file name prefix. Requests to list files in the bucket must include a prefix at least as restrictive as the one in the application key; requests to list other files will be denied. Reading, writing, and deleting are only allowed for matching files.

Using Restricted Keys

Most of the API calls that deal with buckets or files use a bucketId to identify a bucket. But, when using an application key that restricts access to just one bucket, you can't use b2_list_buckets to list all the buckets.

When there is a bucket restriction, the bucketId and the bucketName for that bucket are in the response from b2_authorize_account in the allowed section. You can then use that bucketId in all of your later calls.