Application Keys

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

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:

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 key is good until a new master key is created. Creating a new master key invalidates the old one.
  • Use the master 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 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:

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:

deleteKeys

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

Provides access to these APIs:

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, 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:

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:

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:

writeFiles

Lets clients 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 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:

Bucket Restriction

An application key can be restricted to one bucket. All access to all other buckets will be unauthorized.

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 access these capabilities:

  • listBuckets
  • listFiles
  • readFiles
  • shareFiles
  • writeFiles
  • deleteFiles

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.