Application Keys
    • Dark

    Application Keys

    • Dark

    Article Summary

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

    The master app key is the first key 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. 

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

    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.

    Creating and Using App Keys

    You can create an app key using the Backblaze 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.

    UI SettingAPI ValueFunction
    Name of keykeyNameThis value is the alias for your app key. It is used only for user identification in the UI.
    Allow access to bucketsbucketNameIf enabled, this setting allows access to all buckets.
    If disabled, this setting allows access to only one bucket.
    Type of accesscapabilitiesThis value specifies the type of access: 
    • Read and Write
    • Read Only
    • Write Only
    Allow list all bucket nameslistAllBucketNamesThis 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 prefixnamePrefixThis setting limits access to file names that begin with a specific prefix.
    Duration (seconds)validDurationSecondsThis setting allows you to limit the time before authorization expires. This is a positive integer less than 1000 days (in seconds).

    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 keyAuthorization 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.