From 553517cca0b3be19a40878cfd9d374641d565308 Mon Sep 17 00:00:00 2001
From: Devon Hudson <devon.dmytro@gmail.com>
Date: Thu, 12 Dec 2024 17:25:49 +0000
Subject: [PATCH] Add doc section for auth media (#70)

Co-authored-by: Andrew Morgan <1342360+anoadragon453@users.noreply.github.com>
---
 docs/api.md | 23 +++++++++++++++++++++++
 1 file changed, 23 insertions(+)

diff --git a/docs/api.md b/docs/api.md
index ea6452c..4a658dc 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -181,3 +181,26 @@ Example (generated using the body and public key from the previous examples):
     }
 }
 ```
+
+## Authenticated Media
+
+When accessing media from a Synapse homeserver with authenticated media enabled, an
+`Authorization` HTTP header must be passed along with any request to the Matrix Content Scanner.
+If the `Authorization` header is not present, the content scanner assumes the request is not an
+authenticated media request and will use the old Matrix endpoints.
+
+This header follows the `Authentication Bearer scheme` as [outlined in the Matrix specification](https://spec.matrix.org/v1.12/client-server-api/#using-access-tokens).
+The `access_token` must be the Matrix access token of the client's user.
+The `Authorization` header method must be used, sending the access token as a query string
+parameter is not supported.
+
+Example authorization header:
+
+```
+Authorization: Bearer <access_token>
+```
+
+If a request is made for authenticated media and the access token is invalid, the content scanner
+will respond with HTTP status 502, errcode `MCS_MEDIA_REQUEST_FAILED`.
+If a request is made for authenticated media and the `Authorization` header is missing, the content
+scanner will respond with HTTP status 404, errcode `M_NOT_FOUND`.