Matrix logo

Authenticated Media for Servers

Last updated:

With Matrix 1.11 (via MSC3916), there are new media download endpoints to replace the outdated /_matrix/media/* ones. They are:

Note that the media /upload and /create endpoints are not yet moved over to this new namespace. A future spec release will do that.

The Client-Server API endpoints should be largely the same as their deprecated counterparts with a few minor parameter changes. The Federation API endpoints are a bit trickier. They use a multipart/mixed response format with exactly 2 parts: metadata about the file, and the file itself (or a pointer to the file). This can look like either of the following two examples:

Content-Type: multipart/mixed; boundary=gc0p4Jq0M2Yt08jU534c0p

--gc0p4Jq0M2Yt08jU534c0p
Content-Type: application/json

{}

--gc0p4Jq0M2Yt08jU534c0p
Content-Type: text/plain

This media is plain text. Maybe somebody used it as a paste bin.

--gc0p4Jq0M2Yt08jU534c0p

Content-Type: multipart/mixed; boundary=gc0p4Jq0M2Yt08jU534c0p

--gc0p4Jq0M2Yt08jU534c0p
Content-Type: application/json

{}

--gc0p4Jq0M2Yt08jU534c0p
Location: https://cdn.example.org/ab/c1/2345.txt

--gc0p4Jq0M2Yt08jU534c0p

Note that the second example uses a Location header to point to the file instead. Servers will need to make a regular GET request to the provided URL to fetch the media - Content-Type and Content-Disposition headers will be present on that URL instead of in the headers on the part.

Currently, the metadata object is always an empty JSON object, but in future may contain details about which users are able to view the media. An example in this area is MSC3911.

The new endpoints require authentication like most other federation endpoints.

Additionally, servers will need to try the new download endpoints before falling back to the existing /_matrix/media/* ones. Specifically, if a 404 M_UNRECOGNIZED error is received, servers should fall back rather than treat the media as non-existent.