Contents x
b2_create_key
    • Print
    • Dark
      Light
    Contents

    b2_create_key

      • Print
      • Dark
        Light
      Article summary

      Post
      /b2api/v4/b2_create_key

      Creates a new application key

      There is a limit of 100 million key creations per account.

      NOTE:

      This API endpoint can be called using a GET request by converting the parameters in the request body to query parameters.

      API Versions

      v4 b2_create_key (April 29, 2025)

      Please note: to allow for the creation of Multi-Bucket Application Keys v4 b2_create_key now includes the bucketIds field in the request and response. The bucketId field has been removed in the request and response.


      For information on all API versions, view our API changelog.

      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.

      ExampleACCOUNT_ID
      capabilities
      Array of string Required

      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", "writeBucketNotifications", "listFiles", "readFiles", "shareFiles", "writeFiles", "deleteFiles", "readBucketNotifications", "readFileLegalHolds", "writeFileLegalHolds", "readFileRetentions", "writeFileRetentions", "bypassGovernance", "readBucketLogging", "writeBucketLogging" ]
      keyName
      string Required

      The name for this key. There is no requirement for the key name to be unique. Key names are limited to 100 characters and can contain letters, numbers, and "-", but not I18N characters, such as é, à, and ü.

      Please note: The key name cannot be used to look up the key.

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

      Minimum0
      Maximum86400000
      bucketIds
      Array

      When provided, the new key can only access the specified buckets.

      Example[ "ca1edec684c1f8805b570c17" ]
      namePrefix
      string

      When provided, this parameter limits access to files with names starting with the specified prefix. By default, the restriction is applied to all buckets unless a bucketId is included in the request.

      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, writeBucketNotifications, writeBucketRetentions, readBucketEncryption, writeBucketEncryption, listFiles, readFiles, shareFiles, writeFiles, deleteFiles, readFileLegalHolds, writeFileLegalHolds, readFileRetentions, writeFileRetentions, bypassGovernance, readBucketNotifications, readBucketReplications, writeBucketReplications, readBucketLogging, and writeBucketLogging.

      Example[ "listKeys", "readFiles" ]
      string
      Valid values[ "listKeys", "writeKeys", "deleteKeys", "listAllBucketNames", "listBuckets", "readBuckets", "writeBuckets", "deleteBuckets", "readBucketRetentions", "writeBucketRetentions", "readBucketEncryption", "writeBucketEncryption", "writeBucketNotifications", "listFiles", "readFiles", "shareFiles", "writeFiles", "deleteFiles", "readBucketNotifications", "readFileLegalHolds", "writeFileLegalHolds", "readFileRetentions", "writeFileRetentions", "bypassGovernance" ]
      accountId
      string

      The account that this application key is for.

      ExampleACCOUNT_ID
      expirationTimestamp
      integer

      When present, says when this key will expire, in milliseconds since 1970.

      Minimum0
      Example1671147546259
      bucketIds
      Array

      When present, restricts access to the buckets in the array.

      Example[ "ca1edec684c1f8805b570c17" ]
      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
      statuscodedescription
      400bad_bucket_idThe requested bucket ID does not match an existing bucket.
      400bad_requestThe 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
      statuscodedescription
      401bad_auth_tokenThe auth token used is not valid. Call b2_authorize_account again to either get a new one, or an error message describing the problem.
      401expired_auth_tokenThe auth token used has expired. Call b2_authorize_account again to get a new one.
      401unauthorizedThe 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
      statuscodedescription
      403transaction_cap_exceededTransaction 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?
      What's Next