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 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 tokenb2_create_key
- creates a new application key for your accountb2_delete_key
- deletes one application keyb2_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:
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, 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:
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:
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:
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:
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.