diff --git a/http/src/main/scala/org/apache/pekko/http/scaladsl/server/directives/SecurityDirectives.scala b/http/src/main/scala/org/apache/pekko/http/scaladsl/server/directives/SecurityDirectives.scala
index 5f79daa0a..0f47a34fa 100644
--- a/http/src/main/scala/org/apache/pekko/http/scaladsl/server/directives/SecurityDirectives.scala
+++ b/http/src/main/scala/org/apache/pekko/http/scaladsl/server/directives/SecurityDirectives.scala
@@ -142,6 +142,12 @@ trait SecurityDirectives {
    * The given authenticator determines whether the credentials in the request are valid
    * and, if so, which user object to supply to the inner route.
    *
+   * If no `Authorization: Bearer <token>` header is present, this directive falls back to
+   * extracting the token from the `access_token` query parameter. Per RFC 6750 Section 2.3,
+   * bearer tokens transmitted via query parameters may be leaked in server logs, browser history,
+   * HTTP Referer headers, and proxy logs. For browser-facing APIs, prefer requiring the
+   * `Authorization` header.
+   *
    * @group security
    */
   def authenticateOAuth2[T](realm: String, authenticator: Authenticator[T]): AuthenticationDirective[T] =
@@ -152,6 +158,12 @@ trait SecurityDirectives {
    * The given authenticator determines whether the credentials in the request are valid
    * and, if so, which user object to supply to the inner route.
    *
+   * If no `Authorization: Bearer <token>` header is present, this directive falls back to
+   * extracting the token from the `access_token` query parameter. Per RFC 6750 Section 2.3,
+   * bearer tokens transmitted via query parameters may be leaked in server logs, browser history,
+   * HTTP Referer headers, and proxy logs. For browser-facing APIs, prefer requiring the
+   * `Authorization` header.
+   *
    * @group security
    */
   def authenticateOAuth2Async[T](realm: String, authenticator: AsyncAuthenticator[T]): AuthenticationDirective[T] =
@@ -180,6 +192,9 @@ trait SecurityDirectives {
    * The given authenticator determines whether the credentials in the request are valid
    * and, if so, which user object to supply to the inner route.
    *
+   * Falls back to extracting the token from the `access_token` query parameter if no
+   * `Authorization` header is present. See [[authenticateOAuth2]] for security considerations.
+   *
    * @group security
    */
   def authenticateOAuth2PF[T](realm: String, authenticator: AuthenticatorPF[T]): AuthenticationDirective[T] =
@@ -190,6 +205,9 @@ trait SecurityDirectives {
    * The given authenticator determines whether the credentials in the request are valid
    * and, if so, which user object to supply to the inner route.
    *
+   * Falls back to extracting the token from the `access_token` query parameter if no
+   * `Authorization` header is present. See [[authenticateOAuth2]] for security considerations.
+   *
    * @group security
    */
   def authenticateOAuth2PFAsync[T](realm: String, authenticator: AsyncAuthenticatorPF[T]): AuthenticationDirective[T] =