api: Add support for optional authentication

crates/ruma-common/CHANGELOG.md

@@ -9,6 +9,7 @@ Breaking changes:
   If the field is missing, push rules that depend on it will never match. However, this allows to
   match the `.m.rule.invite_for_me` push rule because usually the `invite_state` doesn't include
   `m.room.power_levels`.
+- Add support for endpoints that take an optional authentication
 
 Improvements:
 

crates/ruma-common/src/api.rs

@@ -484,6 +484,12 @@ pub enum AuthScheme {
     /// It is recommended to use the header over the query parameter.
     AccessToken,
 
+    /// Authentication is optional, and it is performed by including an access token in the
+    /// `Authentication` http header, or an `access_token` query parameter.
+    ///
+    /// It is recommended to use the header over the query parameter.
+    AccessTokenOptional,
+
     /// Authentication is performed by including X-Matrix signatures in the request headers,
     /// as defined in the federation API.
     ServerSignatures,

crates/ruma-common/src/api/metadata.rs

@@ -74,6 +74,11 @@ impl Metadata {
                 Some((header::AUTHORIZATION, format!("Bearer {token}").try_into()?))
             }
 
+            AuthScheme::AccessTokenOptional => match access_token.get_required_for_endpoint() {
+                Some(token) => Some((header::AUTHORIZATION, format!("Bearer {token}").try_into()?)),
+                None => None,
+            },
+
             AuthScheme::ServerSignatures => None,
         })
     }