b2_list_keys
    • Dark
      Light

    b2_list_keys

    • Dark
      Light

    Article Summary

    Get
    /b2api/v3/b2_list_keys

    PLEASE NOTE:

    This API request is now being described as a GET request and not a POST request, as was the case in previous versions of our documentation.

    We made this update because we believe that an API call that retrieves data and does not alter state is more accurately represented as a GET request.

    You may still make a POST request to this endpoint by simply submitting a JSON-formatted request body containing the parameters, with Content-Type set to application/json.


    Lists application keys associated with an account

    Header parameters
    Authorization
    stringRequired

    An account authorization token, obtained from b2_authorize_account.
    The token must have the listKeys capability.

    Query parameters
    accountId
    stringRequired

    The ID of your account.

    maxKeyCount
    string

    The maximum number of keys to return in the response. Default is 100, maximum is 10000.

    NOTE: b2_list_keys is a Class C transaction (see Pricing). The maximum number of keys returned per transaction is 1000. If you set maxKeyCount to more than 1000 and more than 1000 are returned, the call will be billed as multiple transactions, as if you had made requests in a loop asking for 1000 at a time. For example: if you set maxKeyCount to 10000 and 3123 keys are returned, you will be billed for 4 Class C transactions.

    startApplicationKeyId
    string

    The first key to return. Used when a query hits the maxKeyCount, and you want to get more. Set to the value returned as the nextApplicationKeyId in the previous query.

    Responses
    200

    The request succeeded.


    The response headers include the Content-Type that was specified when the file was uploaded. They also include the X-Bz-FileName and X-Bz-Content-Sha1 headers, plus X-Bz-Info-* headers for any custom file info that was provided with the upload. The X-Bz-FileName uses percent-encoding, as if it were a URL parameter.

    Expand All
    object
    keys
    Array of object

    An array of key objects (see below).

    Example[ { "accountId": "12f634bf3cby", "applicationKeyId": "00512f95cf4dcf0000000004y", "bucketId": null, "capabilities": [ "listKeys", "writeKeys", "deleteKeys", "listBuckets", "writeBuckets", "deleteBuckets", "readBuckets", "listFiles", "readFiles", "shareFiles", "writeFiles", "deleteFiles", "readBucketEncryption", "writeBucketEncryption", "bypassGovernance", "readBucketRetentions", "writeBucketRetentions", "readFileRetentions", "writeFileRetentions", "readFileLegalHolds", "writeFileLegalHolds" ], "expirationTimestamp": null, "keyName": "all-bucket-key", "namePrefix": null, "options": [ "s3" ] }, { "accountId": "12f634bf3cbz", "applicationKeyId": "00512f95cf4dcf0000000004z", "bucketId": "e1256f0973908bfc71ed0c1z", "capabilities": [ "listAllBucketNames", "listBuckets", "readBuckets", "listFiles", "readFiles", "shareFiles", "writeFiles", "deleteFiles", "readBucketEncryption", "writeBucketEncryption" ], "expirationTimestamp": null, "keyName": "backup-bucket-key", "namePrefix": null, "options": [ "s3" ] } ]
    object
    accountId
    string

    The account that this application key is for.

    applicationKeyId
    string

    The ID of the newly created key.

    bucketId
    string

    When present, restricts access to one bucket.

    Example4a48fe8875c6214145260818
    capabilities
    Array of string

    A list of strings, each one naming a capability the key has.

    Example[ "listKeys", "writeKeys", "deleteKeys" ]
    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", "readBucketReplications", "writeBucketReplications" ]
    expirationTimestamp
    integer

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

    keyName
    string

    The name assigned when the key was created.

    namePrefix
    string

    When present, restricts access to files whose names start with the prefix.

    options
    Array of string

    When present and set to s3, the key can be used to sign requests to the S3 Compatible API.

    Example[ "s3" ]
    string
    nextApplicationKeyId
    string

    Set if there are more keys beyond the ones that were returned. Pass this value the startApplicationKeyId in the next query to continue listing keys.


    Note that this value may not be a valid application key ID, but can still be used as the starting point for the next query.

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

    Was this article helpful?

    What's Next