Clarify: Send token to discovery endpoints #416 (#417)

Co-authored-by: Stefaan Lippens <[email protected]>

CHANGELOG.md

@@ -30,6 +30,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Fixed the Collection example to use `gsd` instead of `eo:gsd`. [#399](https://github.com/Open-EO/openeo-api/issues/399)
 - Clarify use of `user_id`. [#404](https://github.com/Open-EO/openeo-api/issues/404)
 - Clarify that the relation type `version-history` should include `/.well-known/openeo` in the URL.
+- Clarify that clients should (re-)request capabilities and discovery endpoints with token if available and supported. [#416](https://github.com/Open-EO/openeo-api/issues/416)
 - `GET /`: Removed the superfluous default value for `currency`. [#423](https://github.com/Open-EO/openeo-api/issues/423)
 
 ## [1.1.0] - 2021-05-17

openapi.yaml

@@ -142,6 +142,9 @@ info:
 
     <SecurityDefinitions />
 
+    **Note:** Although it is possible to request several public endpoints for capabilities and discovery that don't require authorization, it is RECOMMENDED that clients (re-)request the public endpoints that support Bearer authentication with the Bearer token once available to also retrieve any private data that is made available specifically for the authenticated user.
+    This may require that clients clear any cached data they retrieved from public endpoints before.
+
     # Cross-Origin Resource Sharing (CORS)
 
     > Cross-origin resource sharing (CORS) is a mechanism that allows restricted resources [...] on a web page to be requested from another domain outside the domain from which the first resource was served. [...]
@@ -1192,6 +1195,10 @@ paths:
         features / extensions and
         [STAC extensions](https://stac-extensions.github.io)
         can be implemented in addition to what is documented here.
+
+        Note: Although it is possible to request public collections without
+        authorization, it is RECOMMENDED that clients (re-)request the collections
+        with the Bearer token once available to also retrieve any private collections.
       tags:
         - EO Data Discovery
       security:
@@ -1319,6 +1326,8 @@ paths:
         features / extensions and
         [STAC extensions](https://stac-extensions.github.io)
         can be implemented in addition to what is documented here.
+
+        Note: Providing the Bearer token is REQUIRED for private collections.
       tags:
         - EO Data Discovery
       security: