b2_create_key
Creates a new application key.
There is a limit of 100 million key creations per account.
Request
Request HTTP Headers
Authorization
required
An account authorization token, obtained from
b2_authorize_account.
The token must have the writeKeys capability.
Request HTTP Message Body Parameters
accountId
required
Your account ID.
capabilities
required
A list of strings, each one naming a capability the new key should have.
Possibilities are:
listKeys,
writeKeys,
deleteKeys,
listAllBucketNames,
listBuckets,
readBuckets,
writeBuckets,
deleteBuckets,
readBucketRetentions,
writeBucketRetentions,
readBucketEncryption,
writeBucketEncryption,
listFiles,
readFiles,
shareFiles,
writeFiles,
deleteFiles,
readFileLegalHolds,
writeFileLegalHolds,
readFileRetentions,
writeFileRetentions, and
bypassGovernance.
keyName
required
A name for this key. There is no requirement that the name be unique. The name cannot be used to look up the key. Names can contain letters, numbers, and "-", and are limited to 100 characters.
validDurationInSeconds
optional
When provided, the key will expire after the given number of seconds, and
will have expirationTimestamp set.
Value must be a positive integer, and must be less than 1000 days (in seconds).
bucketId
optional
When present, the new key can only access this bucket. When set, only
these capabilities can be specified:
listAllBucketNames,
listBuckets,
readBuckets,
readBucketEncryption,
writeBucketEncryption,
readBucketRetentions,
writeBucketRetentions,
listFiles,
readFiles,
shareFiles,
writeFiles,
deleteFiles,
readFileLegalHolds,
writeFileLegalHolds,
readFileRetentions,
writeFileRetentions, and
bypassGovernance.
namePrefix
optional
When present, restricts access to files whose names start with the prefix.
You must set bucketId when setting this.
Response
Response HTTP Status 200
Bucket successfully created. The JSON response will contain:
keyName
required
The name assigned when the key was created.
applicationKeyId
required
The ID of the newly created key.
applicationKey
required
The secret part of the key. This is the only time it will be returned, so you need to keep it. This is not returned when you list the keys in your account.
capabilities
required
A list of strings, each one naming a capability the key has.
Possibilities are:
listKeys,
writeKeys,
deleteKeys,
listAllBucketNames,
listBuckets,
readBuckets,
writeBuckets,
deleteBuckets,
readBucketRetentions,
writeBucketRetentions,
readBucketEncryption,
writeBucketEncryption,
listFiles,
readFiles,
shareFiles,
writeFiles,
deleteFiles,
readFileLegalHolds,
writeFileLegalHolds,
readFileRetentions,
writeFileRetentions, and
bypassGovernance.
accountId
required
The account that this application key is for.
expirationTimestamp
optional
When present, says when this key will expire, in milliseconds since 1970.
bucketId
optional
When present, restricts access to one bucket.
namePrefix
optional
When present, restricts access to files whose names start with the prefix
options
optional
When present, contains a set of strings. Reserved for future use.
Response Errors
Bucket not created.
If possible the server will return a JSON error structure. Errors include:
status |
code |
description |
|---|---|---|
400 |
bad_request |
The request had the wrong fields or illegal values. The message returned with the error will describe the problem. |
401 |
unauthorized |
The auth token used is valid, but does not authorize this call with these parameters. The capabilities of an auth token are determined by the application key used with b2_authorize_account. |
401 |
bad_auth_token |
The auth token used is not valid. Call b2_authorize_account again to either get a new one, or an error message describing the problem. |
401 |
expired_auth_token |
The auth token used has expired. Call b2_authorize_account again to get a new one. |