Listing the buckets you own

You use the HTTP GET method to list the buckets you own. To list the buckets you own, you must be an authenticated user.

The target of a request to list the buckets you own is a tenant (that is, the service point). The list of buckets in the response contains only buckets created in the context of that tenant and only those that have the S3 compatible API enabled. The buckets are listed in alphanumeric order.

The list of buckets you own is returned in an XML response body.

Request line

An S3 compatible request to list the buckets you own has this format:

GET / HTTP/1.1

Required headers

  • Authorization

    Specifies user credentials or requests anonymous access.

  • Date

    Specifies the date and time when the request is being made according to the requester. Normally, this is the current date and time.

    The date and time must always be specified using Greenwich Mean Time (GMT).

    To specify the date and time, use this format:

    DDD, dd MMM yyyy HH:mm:ss (+0000|GMT)

    In this format:

    • DDD

      The three-letter abbreviation for the day of the week, with an uppercase first letter (for example, Mon).

    • dd

      The two-digit day of the month.

    • MMM

      The three-letter abbreviation for the month, with an uppercase first letter (for example, Feb).

    • yyyy

      The four-digit year.

    • HH

      The hour on a 24-hour clock.

    • mm

      The number of minutes.

    • ss

      The number of seconds.

    For example:

    Thu, 23 Mar 2017 14:27:05 +0000

    All S3 compatible requests must include either a Date header or an x-amz-date header. If a request includes both headers, HCP uses the date and time in the x-amz-date header.

  • Host

    Specifies the hostname for the request. The host name identifies either a tenant or a bucket.

    For a tenant, use this format:

    tenant-name.hcp-domain-name

    For a bucket, use this format:

    bucket-name.tenant-name.hcp-domain-name

  • x-amz-date

    Specifies the date and time at which the request is being made according to the requester. Normally, this is the current date and time.

    For the valid values for this header, see the description of the Date header above.

Optional headers

  • x-hcp-pretty-print

    Optionally, requests that the XML response body be formatted for readability. Valid values are:

    • true

      Format the XML response body for readability.

    • false

      Do not apply any special formatting to the XML response body.

    The default is false.

    The values true and false are not case sensitive.

Response headers

  • Content-Type

    Specifies the Internet media type of the response body. For a request to list the contents of a bucket, the value of this header is always application/xml;charset=UTF-8.

  • Date

    The date and time when HCP responded to the request, in Greenwich Mean Time (GMT). The date and time are returned in this format:

    DDD dd MMM yyyy HH:mm:ss GMT

    For example:

    Fri, 18 Sep 2020 14:27:05 GMT

  • Transfer-Encoding

    Indicates that HCP could not determine the size of the response body before formulating the response. For a request to list the buckets you own, the value of this header is always chunked.

Response body

HCP returns the list of buckets you own in an XML response body, in this format:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ListAllMyBucketsResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
     <Owner>
          <ID>bucket-owner-user-id</ID>
          <DisplayName>bucket-owner-username</DisplayName>
     </Owner>
     <Buckets>
Format for a bucket:
          <Bucket>
               <Name>bucket-name</Name>
               <CreationDate>bucket-creation-date-and-time</CreationDate>
          </Bucket>
            .
            .
            .
     </Buckets>
</ListAllMyBucketsResult>
  • Bucket

    Child of the ListAllMyBucketsResult element and container for the Name and CreationDate elements.

    The response body contains one Bucket element for each bucket you own.

  • CreationDate

    Child of the Bucket element.

    The CreationDate element specifies the date and time when the applicable bucket was created, in Greenwich Mean Time (GMT). The date and time are expressed in this format:

    yyyy-MM-ddTHH:mm:ss.SSSZ

    For example:

    2020-02-18T19:46:03.856Z

  • DisplayName

    Child of the Owner element.

    If the bucket owner is identified by an HCP user account, the value of the DisplayName element is the username for that account. If the bucket owner is identified by an AD user account, the value of the DisplayName element is the username of that account followed by an at sign (@) and the AD domain name.

  • ID

    Child of the Owner element.

    If the bucket owner is identified by an HCP user account, the value of the ID element is the user ID for that account. If the bucket owner is identified by an AD user account, the value of the ID element is the SID for that account.

  • ListAllMyBucketsResult

    Root element.

  • Name

    Child of the Bucket element.

    The Name element specifies the name of a bucket.

  • Owner

    Child of the ListAllMyBucketsResult element and container for the DisplayName and ID elements.

    The Owner element identifies the owner of the applicable bucket.

Return codes

The table below describes HTTP status codes that can be returned in response to a request to list the buckets you own.

CodeMeaningDescription
200OKHCP successfully retrieved the list of buckets you own.
403Forbidden

Possible reasons include:

  • The credentials provided with the request are invalid.
  • The tenant does not currently support use of the S3 compatible API for listing the buckets you own.
  • The specified tenant does not exist.
500Internal Server Error

An internal error occurred.

If this error persists, contact your tenant administrator.

503Service Unavailable

HCP is temporarily unable to handle the request, probably due to system overload, maintenance, or upgrade. Try the request again, gradually increasing the delay between each successive attempt.

If this error persists, contact your tenant administrator.

Example: Listing the buckets you own

Here’s a sample GET request that returns a list of the buckets owned by user lgreen in the context of the europe tenant.

Request with s3curl command line

./s3curl.pl --id=lgreen -- -k "https://europe.hcp.example.com"
     -H "x-hcp-pretty-print: true"

Request headers

GET / HTTP/1.1
Host: europe.hcp.example.com
Date: Fri, 07 February 2020 17:19:26 +0000
Authorization: AWS bGdyZWVu:Gek+OrFpyg06Bufgg+TW6kH5ISA=
x-hcp-pretty-print: true

Response headers

HTTP/1.1 200 OK
Date: Fri, 07 February 2020 17:19:26 GMT
Content-Type: application/xml;charset=UTF-8
Transfer-Encoding: chunked

Response body

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ListAllMyBucketsResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
     <Owner>
          <ID>b9d39144-a081-4762-b0e8-b8fb51e10192</ID>
          <DisplayName>lgreen</DisplayName>
     </Owner>
     <Buckets>
          <Bucket>
               <Name>finance</Name>
               <CreationDate>2019-03-18T12:59:11.898Z</CreationDate>
          </Bucket>
          <Bucket>
               <Name>human-resources</Name>
               <CreationDate>2019-03-18T19:46:03.856Z</CreationDate>
          </Bucket>
     </Buckets>
</ListAllMyBucketsResult>