Overview
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
Prerequisites
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.
| Request | Request URL |
|---|---|
| Get Temp S3 Creds for Prefix | https://geobigdata.io/s3creds/v1/prefix |
| Get Temp S3 Creds for Prefix and specify the duration | https://geobigdata.io/s3creds/v1/prefix?duration=<duration value> |
| Get temp creds-Folder | https://geobigdata.io/s3creds/v1/folder/?folder_path?duration |
| Get temp creds-Object | https://geobigdata.io//s3creds/v1/object/?object_path?duration |
| Get Prefix Size | https://geobigdata.io/s3creds/v1/prefix/<Prefix> |
| Get Download URL for an object | https://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 Type | Value |
|---|---|
| Minimum | 900 seconds (.25 hours) |
| Default | 3600 seconds (1 hour) |
| Maximum | 129600 seconds (36 hours) |
Error Codes
A 404 error code means the requested Prefix, Folder, or Object does not exist and is required.
Updated about a year ago
What's Next
Once you have your temporary credentials, use the AWS CLI to manage your S3 contents.
| Manage S3 Contents with the AWS CLI |