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.
|Web UI Setting||API Value||Function|
|Name of key||keyName||This value is the alias for your app key. It is used only for user identification in the Backblaze web UI.|
|Allow access to buckets||bucketName||If enabled, this setting allows access to all buckets.|
If disabled, this setting allows access to only one bucket.
|Type of access||capabilities||This value specifies the type of access: |
|Allow list all bucket names||listAllBucketNames||This setting allows or disallows the listing of all bucket names that include bucket creation dates.|
This is selectable only when the bucket access is limited to a single bucket.
This setting is required for the S3 List Buckets API operation.
|File name prefix||namePrefix||This setting limits access to file names that begin with a specific prefix.|
|Duration (seconds)||validDurationSeconds||This setting allows you to limit the time before authorization expires. This is a positive integer less than 1000 days (in seconds).|
Related API Operations
The following API calls are related to app keys:
b2_authorize_accountThis 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_keyThis 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_delete_keyThis operation deletes one app key.
b2_list_keysThis operation lists all of the app keys in your account.
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:
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.