Authentication

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 for Discovery Portal. If you don't already have access to Discovery Portal, see here.

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:

https://auth.hydrosat.com/oauth2/token

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.

{
    "access_token": "<token_value>",
    "expires_in": 3600,
    "token_type": "Bearer"
}

'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:

{
"client_id":"<clientID>",
"client_secret":"<clientsecret>"
}

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.

tokenUrl = "https://auth.hydrosat.com/oauth2/token"

with open('creds.json') as f:
    creds = json.loads(f.read())

client_id = creds["client_id"]
client_secret = creds["client_secret"]

payload = f'grant_type=client_credentials&client_id={client_id}&client_secret={client_secret}'
headers = {
  'Content-Type': 'application/x-www-form-urlencoded',
}

token_response = requests.request("POST", tokenUrl, headers=headers, data=payload)
token_data = token_response.json()
access_token = token_data["access_token"]

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.

STACheaders = {"Authorization":f"Bearer {access_token}"}
collection_response = requests.request("GET", 'https://stac.hydrosat.com/collections', headers=STACheaders)
collection_data = collection_response.json()
print(collection_data)

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.