b2_create_key
- Print
- DarkLight
b2_create_key
- Print
- DarkLight
Article Summary
Share feedback
Thanks for sharing your feedback!
Post
/b2api/v3/b2_create_key
Creates a new application key
There is a limit of 100 million key creations per account.
PLEASE NOTE:
This API endpoint can be called using a GET request by converting the parameters in the request body to query parameters.
Header parameters
Authorization
stringRequired
An account authorization token, obtained from b2_authorize_account.
The token must have the writeKeys capability.
Body parameters
object
accountId
string Required
Your account ID.
ExampleYOUR_ACCOUNT_ID
capabilities
Array of stringRequired
A list of strings, each one naming a capability the new key should have.
Example[ "listKeys", "writeKeys" ]
string
Valid values[ "listKeys", "writeKeys", "deleteKeys", "listAllBucketNames", "listBuckets", "readBuckets", "writeBuckets", "deleteBuckets", "readBucketRetentions", "writeBucketRetentions", "readBucketEncryption", "writeBucketEncryption", "listFiles", "readFiles", "shareFiles", "writeFiles", "deleteFiles", "readFileLegalHolds", "writeFileLegalHolds", "readFileRetentions", "writeFileRetentions", "bypassGovernance" ]
keyName
string 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.
Max length100
PatternA-Za-z0-9\-]+
Examplekey-0003
validDurationInSeconds
integer
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).
Maximum86400000
Minimum0
bucketId
string
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.
Examplee1256f0973908bfc71ed0c1z
namePrefix
string
When present, restricts access to files whose names start with the prefix. You must set bucketId when setting this.
Examplefoo
Responses
200
Successful operation
object
keyName
string
The name assigned when the key was created.
Examplekey-0003
applicationKeyId
string
The ID of the newly created key
Example00512f95cf4dcf0000000004z
applicationKey
string
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.
ExampleK0041ZMxZEop4JkYUJqEei1ZSep14zz
capabilities
Array of string
list of strings, each one naming a capability the key has. This list could include: listKeys, writeKeys, deleteKeys, listAllBucketNames, listBuckets, readBuckets, writeBuckets, deleteBuckets, readBucketRetentions, writeBucketRetentions, readBucketEncryption, writeBucketEncryption, listFiles, readFiles, shareFiles, writeFiles, deleteFiles, readFileLegalHolds, writeFileLegalHolds, readFileRetentions, writeFileRetentions, bypassGovernance, readBucketReplications, and writeBucketReplications.
Example[ "listKeys", "readFiles" ]
string
Valid values[ "listKeys", "writeKeys", "deleteKeys", "listAllBucketNames", "listBuckets", "readBuckets", "writeBuckets", "deleteBuckets", "readBucketRetentions", "writeBucketRetentions", "readBucketEncryption", "writeBucketEncryption", "listFiles", "readFiles", "shareFiles", "writeFiles", "deleteFiles", "readFileLegalHolds", "writeFileLegalHolds", "readFileRetentions", "writeFileRetentions", "bypassGovernance" ]
accountId
string
The account that this application key is for.
ExampleYOUR_ACCOUNT_ID
expirationTimestamp
integer
When present, says when this key will expire, in milliseconds since 1970.
Minimum0
Example1671147546259
bucketId
string
When present, restricts access to one bucket.
Examplee1256f0973908bfc71ed0c1z
namePrefix
string
When present, restricts access to files whose names start with the prefix
Examplefoo
options
Array of string
When present, contains a set of strings. Reserved for future use.
Example[ "s3" ]
string
Valid values[ "s3" ]
400
| status | code | description |
|---|---|---|
| 400 | bad_bucket_id | The requested bucket ID does not match an existing bucket. |
| 400 | bad_request | The request had the wrong fields or illegal values. The message returned with the error will describe the problem. |
object
status
integer
The numeric HTTP status code. Always matches the status in the HTTP response.
Example400
code
string
A single-identifier code that identifies the error.
Exampleinvalid_bucket_name
message
string
A human-readable message, in English, saying what went wrong.
Examplebucket name is too long
401
| status | code | description |
|---|---|---|
| 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. |
| 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. |
object
status
integer
The numeric HTTP status code. Always matches the status in the HTTP response.
Example400
code
string
A single-identifier code that identifies the error.
Exampleinvalid_bucket_name
message
string
A human-readable message, in English, saying what went wrong.
Examplebucket name is too long
403
| status | code | description |
|---|---|---|
| 403 | transaction_cap_exceeded | Transaction cap exceeded. To increase your cap, sign in to your B2 Cloud Storage account online. Then select the Caps & Alerts link in the B2 Cloud Storage section of the sidebar. |
object
status
integer
The numeric HTTP status code. Always matches the status in the HTTP response.
Example400
code
string
A single-identifier code that identifies the error.
Exampleinvalid_bucket_name
message
string
A human-readable message, in English, saying what went wrong.
Examplebucket name is too long
Was this article helpful?