Application Keys

Application keys (app keys) control access to your Backblaze B2 Cloud Storage account.

You can create standard app keys that are limited to a bucket. These keys have a specific file prefix, limited capabilities, and can expire. Standard app keys are useful because they continue to work even when you change the master app key. You can also delete a standard app key to remove access without disrupting other users.

The master app key is the first key that you have access to and provides complete access to your account. This key has all capabilities, access to all buckets, and has no file prefix restrictions or expiration. Your master app key is shown only when you generate it, and it is not shown again. You should save your master app key in a secure location if you plan to use it more than once. Your master app key becomes invalid if you generate a new one. After you sign in to your Backblaze account, you can find the master app key ID for your account on the App Keys page.

If you highlight an entire value with your mouse cursor and copy the selection, it may copy extra formatting in the form of hidden characters. Backblaze recommends that you check for these hidden characters if you paste the value into a program for authorization.

If you use a Backblaze B2 integration partner, confirm that their app supports app keys.

When to Use Standard and Master Application Keys

Because a master application key grants broad access privileges, you should use it only in situations where that level of access is necessary. Otherwise, it is safer to use a standard application key that is limited to the level of access that a user needs. The following use cases demonstrate when to use a standard app key versus a master application key:

Use a standard application key for the following cases:

• You are using the S3-Compatible API.
• You have a bucket that is dedicated to media distribution, and you want an app key with read-only access.
• You are running an application that requires access to specific data that is stored in specific buckets.
• You made a web application that lets users upload files to a designated bucket.
• You are integrating with third-party applications, such as Cyberduck or LucidLink.

Use a master application key for the following cases:

• You are using the Partner API.
• You are running an account-level application that administers groups or buckets.

Creating and Using App Keys

You can create an app key using the Backblaze web UI, or you can use the b2_create_key operation in the Native API. You can limit app keys to a single storage bucket, or even to specific files within a bucket.

You can create multiple app keys. For example, if you create a cell phone app, you can create an app key for each of your customers. The limit is currently 100 million app keys per account, but contact the Backblaze sales team if you need more.

The following table includes each app key setting and their corresponding functions.

Related API Operations

The following API calls are related to app keys:

• b2_authorize_account This operation uses an app key to generate an authorization token.The authorization token that is generated when you use an app key is limited to the capabilities of that app key. Authorization tokens expire after 24 hours. You can use your app key to create new authorization tokens as they expire. 
• b2_create_key This operation creates a new app key for your account. You can configure expiration times for an app key. However, if an app key expires, you can not use it to generate authorization tokens, and it will not be listed by b2_list_keys.
• b2_delete_key This operation deletes one app key.
• b2_list_keys This operation lists all of the app keys in your account.

Bucket Restriction

You can use an app key to restrict access to one bucket. Access to all of the other buckets is then unauthorized. However, for app keys with the listAllBucketNames capability, you can still view all of the bucket names in the account.

If you make a b2_list_buckets request with an app key that is restricted to one bucket, you must include the bucket ID (or name) in the request for that bucket.

App keys that are restricted to a bucket can include only the following capabilities:

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

You can also restrict app keys to the files in a bucket that match a file name prefix. To list the files in the bucket, you must include a prefix at least as restrictive as the one in the app key; requests to list other files are denied. Reading, writing, and deleting are allowed only for matching files.

Using Restricted Keys

Most of the API calls that are associated with buckets or files use a bucketId to identify a bucket. However, when you use an app key that restricts access to just one bucket, you cannot use b2_list_buckets to list all of 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 subsequent calls.