Hydrosat's Discovery STAC API requires a bearer token for authentication and authorization.

This article covers the process of using a client ID and secret pair to generate a bearer token and then including that bearer token in requests to the STAC API.

For documentation on how to create an API client ID and secret, view the Managing API Clients article.

Using a Client ID and Secret to get a Token

When creating an API client in the Discovery Portal, you will be issued a client ID and client secret for that API client.

The client ID and secret are unique credentials that allow the client to generate a temporary bearer token which provides access to use the API with any permissions provided to that client.

The client can request a valid token by submitting its client ID and secret in a form POST payload to the following token url:

The response contains the values shown below, including the amount of time the token will live before expiring, in seconds. Because a token is only temporarily valid, the client must manage getting refreshed tokens regularly in order to have consistent access to the API.

'Get Token' Example

The example below assumes that the user has stored their API client ID and secret in a separate file called creds.json with the following structure:

For security, we suggest setting credential file permissions to 600 (chmod 600 creds.json) so that only the owner has read and write access. Consult with your organization's security team to ensure you are complying with preferred methods for storing and accessing API client credentials.

The Python example below covers using the credentials stored in creds.json to generate a new token for use with the Hydrosat Discovery STAC API and storing the resulting token in the access_token variable.

Using the Token to Make a STAC Request

Once the client has a valid token, it can make requests to the STAC API as normal.

In the below example, the token is stored in the access_token variable from the previous code example and is used to make a request to the /collections endpoint using the requests Python library.

Unauthenticated Requests

Unauthenticated requests to the STAC API will return an error (401 Unauthorized Error)

For lengthier examples and next steps, please see our code examples in Github.

Visit our example code Github repo for helpful tutorials for using our STAC API and imagery.

Hydrosat's Data Discovery STAC API is available at https://stac.hydrosat.com/. The STAC API requires authentication using a bearer token.

SpatioTemporal Asset Catalog (STAC) API

This page includes high-level information on the basic features of the API and provides examples for a few methods of working with it.

Through Hydrosat's STAC API, you can search for data that meets your needs. Data are stored as Cloud-Optimized GeoTIFFs (COGs), which means you can either download the full files or stream only the parts you need using standard web requests.

Learn more:

• STAC (SpatioTemporal Asset Catalog): stacspec.org

• Cloud-Optimized GeoTIFFs (COGs): cogeo.org

While you can use the STAC API directly, we recommend using one of the following tools to make it easier:

• Python library: pystac-client documentation

STAC API Endpoints

STAC Catalog Structure

Hydrosat's STAC catalog is organized into four collections.

Each collection contains a series of items representing individual scenes. Within each item, you will find metadata and links to associated imagery.

STAC Query Examples

pystac-client

We recommend using the pystac-client Python library. This library is specifically designed to interact with STAC catalogs and APIs. Complete documentation for this library can be found here. More examples with pystac are included in our full Github examples.

import pystac
from pystac_client import Client

# Connect to the STAC catalog.
# See our page on authentication for how to set up your headers.
catalog = Client.open('https://stac.hydrosat.com/', headers=headers)

# Search for Level-2 data intersecting southern Australia from 19 April 2026
search = catalog.search(
        collections = ['vz-l2'],
        bbox = [140.173825, -37.63983, 149.28178, -34.929824],
        datetime = ["2026-01-19T00:00:00Z", "2026-04-19T00:00:00Z"]
    )

# Print a list of STAC items returned from the search    
items = list(search.items())
print(items)

curl

The STAC server can also be queried directly from your terminal using curl. For example, you can use a POST request to perform a query, specifying the search parameters as JSON-formatted raw data. For more information, please see the curl docs.

curl -X POST \
--header 'Content-Type: application/json' \
--data '{
    "collections": ["vz-l2"],
    "bbox": [140.173825, -37.63983, 149.28178, -34.929824],
    "datetime": "2026-04-01T00:00:00Z/2025-05-01T00:00:00Z"
}' \
https://stac.hydrosat.com/

If your Discovery Platform account is configured to allow data downloads, your download entitlements are based on areas of interest and/or specific scene IDs. If you already know what your entitlement areas of interest (Download Access Areas) or scene IDs are, you can use that information to query data via the STAC API.

For help locating downloadable data in the Discovery Portal, check out this separate article.

If you don't know what your download entitlements are, you can look them up using Hydrosat's Accounts API.

If you would like to get access to downloadable data, contact our sales team.

Using Accounts API

Accounts API uses the same bearer token Authentication and API credentials as the STAC API.

Use the following endpoint to GET the active access policy for your account, which includes information about your download entitlements.

https://accounts.hydrosat.com/v2/me/access-policies

The polygons for area of interest-based download entitlements are listed within product_entitlements and scene ID-based entitlements are listed within scene_entitlements. The product_entitlements and scene_entitlements also include information about which STAC collections are you entitled to download from.

A product_entitlements example with a single polygon areas_of_interest is shown below.

A scene_entitlements example containing 2 scene_ids is shown below.

Visit our status page and sign up for notifications to get the latest information on our STAC API availability.