# Authentication

Hydrosat's 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](/data-discovery-portal/managing-api-clients.md) article.

### Using a Client ID and Secret to get a Token

When creating an API client in the Data Discovery web interface, 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:

```json
{
"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 Data Discovery STAC API and storing the resulting token in the `access_token` variable.

```python
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](/stac-api-reference-and-specification.md) 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.

```python
STACheaders = {"Authorization":f"Bearer {access_token}"}
collection_response = requests.request("GET", 'https://stac-beta.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](/stac-api-reference-and-specification/example-code-github-repo.md).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://satdocs.hydrosat.com/stac-api-reference-and-specification/authentication.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.