Authentication

All write requests require authentication. We support two authentication methods:

1. Session authentication: For users accessing the data via the web-based admin interface.
2. JSON Web Token Authentication: For programmatic access via the STAC API directly.

WARNING

Basic authentication and token authentication were removed in STAC API version v1.

Session Authentication

Users can browse geodata in the "admin interface", a web-based UI available to selected users. Upon successful login, the service issues a session cookie that authenticates subsequent requests from the browser.

Session authentication is designed specifically for browser-based workflows and may not work with non-browser clients or all API endpoints.

JSON Web Token Authentication

JWT authentication is the recommended approach for API clients performing write operations programmatically.

JWT authentication involves two steps:

1. Obtain a JWT token from Amazon Cognito's InitiateAuth API.
2. Include the token in the HTTP Authorization header using the Bearer scheme as defined in RFC 6750.

To obtain a JWT token, use Amazon Cognito’s InitiateAuth API by sending your username and password, along with your client ID. For example:

curl --request POST \
--url https://cognito-idp.eu-central-1.amazonaws.com/ \
--header 'Content-Type: application/x-amz-json-1.1' \
--header 'X-Amz-Target: AWSCognitoIdentityProviderService.InitiateAuth' \
--data '{
    "AuthFlow": "USER_PASSWORD_AUTH",
    "AuthParameters": {
      "PASSWORD": "I_love_Minnie_Mouse",
      "USERNAME": "MickeyMouse"
    },
    "ClientId": <CLIENT_ID>
}' | jq -r .AuthenticationResult.AccessToken

Replace the values for PASSWORD, USERNAME and ClientId with your actual credentials.

The response from InitiateAuth is a JSON document containing the token under AccessToken.

No token in response

In some cases, the response may not include a token. For example, this can happen if a password update or multi-factor authentication (MFA) is required. AWS provides an SDK to simplify handling these situations

Token expiration

The access token you receive is valid only for a limited time, as specified by the AuthenticationResult.ExpiresIn field. After it expires, your application must obtain a new token either by re-authenticating or by using the refresh token, which is typically valid for a longer period.

Once you have a valid JWT token (for example, 123456), you can create a new asset by including the token in the Authorization header:

curl --request PUT \
--url https://data.geo.admin.ch/api/stac/v1/collections/ch.swisstopo.swisstlmregio/items/swisstlmregio_2020/assets/swisstlmregio_2020_2056.gdb.zip \
--header 'Authorization: Bearer 123456' \
--header 'Content-Type: application/json' \
--data '{
    "id": "swisstlmregio_2020_2056.gdb.zip",
    "item": "swisstlmregio_2020",
    "type": "application/x.shapefile+zip",
    "proj:epsg": 2056,
    "file:checksum": "12200ADEC47F803A8CF1055ED36750B3BA573C79A3AF7DA6D6F5A2AED03EA16AF3BC"
}'