S3 Storage Service API Requests

The GBDX S3 Storage Service is a set of API Endpoints that let the user request temporary credentials to the GBDX S3 location, get the size of an S3 prefix, and generate a download url for a file.

Last Updated: April 24, 2019


The GBDX S3 Storage Service is a set of API endpoints that let you:

  • Get temporary credentials to a GBDX S3 location. You can then use these credentials to manage your GBDX S3 contents with the AWS CLI.
  • Get the size of your S3 prefix
  • Get a download url for a file


All GBDX API requests require a token for authentication. See Authentication Course for more information.

An API client such as Postman is the simplest way to make a direct API request. See Postman Instructions & Collections

API Request Headers

S3 Storage Service API requests must include the following header:

Authorization: Bearer {{token}}

API Endpoints

The S3 storage service includes the following API endpoints. The names in the "Request" column link to a "Try it Out" page for the API request.

RequestRequest URL
Get Temp S3 Creds for Prefixhttps://geobigdata.io/s3creds/v1/prefix
Get Temp S3 Creds for Prefix and specify the durationhttps://geobigdata.io/s3creds/v1/prefix?duration=<duration value>
Get temp creds-Folderhttps://geobigdata.io/s3creds/v1/folder/?folder_path?duration
Get temp creds-Objecthttps://geobigdata.io//s3creds/v1/object/?object_path?duration
Get Prefix Sizehttps://geobigdata.io/s3creds/v1/prefix/<Prefix>
Get Download URL for an objecthttps://geobigdata.io/s3creds/v1/object/url?object_name=folder/file.txt

Temporary Credentials

The credentials provided by the GBDX S3 Storage Service are temporary and session-based. When a request is made for credentials, the system will return:

  • Bucket (The S3 Bucket is gbd-customer-data)
  • Prefix (The Prefix is typically your account ID)
  • S3_access_key
  • S3_secret_key
  • S3_session_token

Session Duration

The default duration that the credentials are valid is 3600 seconds. The requester can change the duration when making an API request. The valid range for duration is 900 seconds to 129600 seconds.

Duration TypeValue
Minimum900 seconds (.25 hours)
Default3600 seconds (1 hour)
Maximum129600 seconds (36 hours)

Error Codes

A 404 error code means the requested Prefix, Folder, or Object does not exist and is required.

What’s Next

Once you have your temporary credentials, use the AWS CLI to manage your S3 contents.