# How to access restricted data with a token

Some data at eodc is only available to signed-in users or to users with approved access.
This guide shows how to get a token for your eodc account and how to use it to find and
download such data, both in the eodc data catalogue and in customer STAC catalogues.

## Two catalogues, one token

| | eodc data catalogue (`catalogue.services.eodc.eu`) | Customer STAC catalogues (`cstac.discovery.eodc.eu`) |
|---|---|---|
| Finding collections and items | Open to everyone, no token | Token needed, unless the collection is public. Without a token, restricted collections don't appear in `/collections` or `/search`. |
| Downloading data | Token needed for restricted collections and for collections that need an eodc account | If the data is hosted at eodc (`data.eodc.eu`): token needed, same as in the eodc data catalogue. If the data is hosted elsewhere: depends on that host. |

The same token works for both catalogues and for downloads from `data.eodc.eu`. Send it
in the `Authorization` header of every request:

```
Authorization: Bearer <token>
```

Access to a restricted collection comes from a group in your eodc account, for example
`/services/data-access/<group>`. You get it after your access request is approved, see
[Get Access](../getting-started/access).

## Get a token

The recommended way is `EODCConnection` from
[eodc-connect](https://pypi.org/project/eodc-connect/):

```
pip install eodc-connect
```

```python
from getpass import getpass

from eodc_connect.auth import EODCConnection

conn = EODCConnection("your.name@example.org", getpass("Enter your password: "))
token = conn.get_access_token()
```

Tokens are short-lived. The lifetime in seconds is in `conn.token["expires_in"]`. In
longer scripts, refresh the token before you use it:

```python
if conn.is_token_expired():
    conn.refresh()
token = conn.get_access_token()
```

For clients other than Python, such as `curl` or GDAL on the command line, request the
token directly from eodc's identity service:

```bash
curl -s https://bouncer.eodc.eu/auth/realms/EODC/protocol/openid-connect/token \
  -d grant_type=password \
  -d client_id=eodc-connect \
  -d username=your.name@example.org \
  --data-urlencode password="$EODC_PASSWORD"
```

The response contains the token in `access_token` and its lifetime in seconds in
`expires_in`.

## Check your access

The groups of your account are in the token. To check them:

```python
print(conn.access_token_decoded["groups"])
```

After you have been added to a group, for example after an approved access request,
get a new token. Existing tokens don't contain the new group.

## eodc data catalogue: search without a token, download with a token

Searching works without a token. Downloading an asset needs it:

```python
import requests
from pystac_client import Client

catalogue = Client.open("https://catalogue.services.eodc.eu")
item = next(catalogue.search(collections=["S1_SAR_COG"], bbox=[15, 47, 17, 49], max_items=1).items())
href = item.assets["VV"].href

response = requests.get(
    href,
    headers={"Authorization": f"Bearer {token}"},
    allow_redirects=False,
    timeout=60,
)
print(response.status_code)  # 302: ready to download, 202: being staged, try again later
```

A `302` points to a short-lived download link in `response.headers["Location"]`. Fetch
that link without the `Authorization` header. For Copernicus Sentinel data, which can
take a few minutes to be staged, see
[Copernicus Sentinel Data Access](sentinel-data-access) for a complete download loop.

## Customer STAC catalogues: send the token with the search too

In a customer STAC catalogue, the token is also needed to find restricted collections.
Pass it to `pystac-client` as a header:

```python
from pystac_client import Client

cstac = Client.open(
    "https://cstac.discovery.eodc.eu",
    headers={"Authorization": f"Bearer {token}"},
)
print([collection.id for collection in cstac.get_collections()])

items = cstac.search(collections=["<collection-id>"], max_items=10).item_collection()
```

Always filter by collection when you search. Item IDs, such as tile names, can be the
same in several collections.

Where the assets are downloaded from depends on where the data is hosted. The
organisation that manages the collection decides this:

- **Hosted at eodc** (asset links start with `https://data.eodc.eu`): download with the
  same token, as in the eodc data catalogue:

  ```python
  href = items[0].assets["<asset-key>"].href
  response = requests.get(href, headers={"Authorization": f"Bearer {token}"}, timeout=60)
  ```

- **Hosted elsewhere** (for example on a university's own server): the asset links point
  to that server, and access depends on it. Your eodc token isn't needed there. Don't send
  it to hosts outside eodc.

## Reading data directly with GDAL, rioxarray or odc-stac

GDAL-based tools read from URLs with HTTP range requests. For assets that `data.eodc.eu`
serves directly, pass the token to GDAL as a header. GDAL then sends it with every
request, so only set it when you read from `data.eodc.eu`:

```python
import os

os.environ["GDAL_HTTP_HEADERS"] = f"Authorization: Bearer {token}"
```

For assets that `data.eodc.eu` answers with a `302` redirect (such as Copernicus Sentinel
data), first request the download link as shown above, then open that link without the
token. The link is signed for `GET` requests only, so turn off GDAL's `HEAD` request:

```python
import os
import rioxarray

os.environ["CPL_VSIL_CURL_USE_HEAD"] = "NO"
os.environ["GDAL_DISABLE_READDIR_ON_OPEN"] = "EMPTY_DIR"

da = rioxarray.open_rasterio(response.headers["Location"], masked=True)
```

## Troubleshooting

| What you see | Meaning | What to do |
|---|---|---|
| `401` or `403` from `data.eodc.eu` | No token, the token has expired, or your account has no access to this collection | Get a new token or refresh it. If that doesn't help, check your groups and request access. |
| `401` from `cstac.discovery.eodc.eu` | The token is invalid or has expired | Get a new token or refresh it |
| Collection missing in `cstac.discovery.eodc.eu` (`/collections/<id>` returns `404`, searches return no items) | No token sent, or your account has no access to this collection | Send the token. If it's still missing, request access, then get a new token. |

If you still can't access data you have been approved for, contact
[support@eodc.eu](mailto:support@eodc.eu) with the collection ID and the time of the request.