Authentication

Certain services are protected with authentication. This page explains how to obtain an access token that can be used to access these services.

Request token

The OpenID Connect (OIDC) Direct Access Grant, also known as the OAuth2 Resource Owner Password Credentials Grant, allows you to obtain an access token by providing your username and password. To get an access token, send a POST request to the token endpoint: https://sso.terrascope.be/auth/realms/terrascope/protocol/openid-connect/token.

The request should contain the following parameters:

  • grant_type: password
  • client_id: public
  • username: your Terrascope username
  • password: your Terrascope password

This will result in the following HTTP request:

POST /auth/realms/terrascope/protocol/openid-connect/token HTTP/1.1
Host: sso.terrascope.be
Content-Type: application/x-www-form-urlencoded

grant_type=password&client_id=public&username=<username>&password=<password>

The response will look like the example below:

{
    "access_token": "eyJhb...",
    "expires_in": 300,
    "refresh_expires_in": 3600,
    "refresh_token": "eyJhb...",
    "token_type": "Bearer",
    "not-before-policy": 0,
    "session_state": "...",
    "scope": "profile email"
}

The provided access token can now be used to access supported services. The access token is included in the Authorization header of the request to the service, for example for downloading WorldCover data:

GET /download/WORLDCOVER/ESA_WORLDCOVER_10M_2020_V100/MAP/ESA_WorldCover_10m_2020_v100_N00E006_Map/ESA_WorldCover_10m_2020_v100_N00E006_Map.tif HTTP/1.1
Host: services.terrascope.be
Authorization: Bearer eyJhb...

Refresh token

The token obtained above will expire after a given time. In order to avoid having to request a new access token using the user credentials every time, it is possible to refresh the token with the refresh token that is provided in the response. This is also done by sending a POST request to the token endpoint, but with different parameters: * grant_type: refresh_token * client_id: public * refresh_token: the refresh token provided in the previous call to the token endpoint

This will result in the following HTTP request:


POST /auth/realms/terrascope/protocol/openid-connect/token HTTP/1.1
Host: sso.terrascope.be
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&client_id=public&refresh_token=eyJhb...

The response of this request will again contain an access and refresh token.

Back to top