# MSC4170: 403 error responses for profile APIs Matrix currently defines the following [client-server APIs] for profile look-ups: - [`GET /_matrix/client/v3/profile/{userId}`] - [`GET /_matrix/client/v3/profile/{userId}/avatar_url`] - [`GET /_matrix/client/v3/profile/{userId}/displayname`] These endpoints also support look-up over federation via the accompanying [server-server API]: - [`GET /_matrix/federation/v1/query/profile`] Each of these endpoints has a documented 404 response for the case that no profile information is available. > 404 There is no profile information for this user or this user does not exist. > > 404 There is no avatar URL for this user or this user does not exist. > > 404 There is no display name for this user or this user does not exist. > > 404 The user does not exist or does not have a profile. However, `GET /_matrix/client/v3/profile/{userId}` additionally reserves a 403 status code that is not available on the other endpoints and can be used to deny profile look-ups. > 403 The server is unwilling to disclose whether the user exists and/or has profile information. Unfortunately, the concrete semantics of when to respond with 403 are not fully spelled out in the spec and understanding prior proposals' intention requires some archeology (see the history section below). The current proposal aims to restore consistency among the profile endpoints by standardizing their 403 error response format and behaviour. ## Proposal For the endpoints in the client-server API - [`GET /_matrix/client/v3/profile/{userId}`] - [`GET /_matrix/client/v3/profile/{userId}/avatar_url`] - [`GET /_matrix/client/v3/profile/{userId}/displayname`] homeservers MUST at a minimum allow profile look-up for users that either share a room with the requester or reside in a public room known to the homeserver (i.e, the same requirements as [`POST /_matrix/client/v3/user_directory/search`])[^3]. In all other cases, homeservers MAY deny profile look-up by responding with 403 `M_FORBIDDEN`. If a remote user is queried through the client-server endpoints and the query is not denied per the preceding paragraph, homeservers SHOULD query the remote server for the user's profile information. Homeservers MAY deny profile look-up over federation by responding with 403 `M_FORBIDDEN` to [`GET /_matrix/federation/v1/query/profile`]. To be clear: there is no requirement to return profiles of users in public or shared rooms over the federation API. Homeservers MAY choose whether to respond with 403 or 404 when the requested user does not exist. If the server denies profile look-up in all but the required cases, 403 is RECOMMENDED. ## Potential issues Synapse already complies with this proposal in its default configuration. However, its `limit_profile_requests_to_users_who_share_rooms` config setting is only partially compatible with this proposal because it disallows profile look-up for users in public rooms that the requester does not share a room with. This inconsistency would need to be fixed if this proposal is accepted into the spec. ## Alternatives None. ## Security considerations This proposal allows server administrators to lock down profile look-ups via the client-server API for all situations except those in which the profile information is already available to the requester via room membership. This complements the existing ability to deny profile look-ups on the server-server API and, if configured accordingly, increases privacy for users. ## History In [2017], the user directory API, [`POST /_matrix/client/v3/user_directory/search`], which closely relates to the profile APIs, was introduced into the spec. Since its inception, it contained the requirement for servers to consider (at least) users from shared and public rooms in the search. Later, [MSC1301] proposed a 403 `M_USER_NOT_PUBLIC` response on all four profile endpoints to optionally disallow profile look-up for users that the requester does not share a room with. This MSC was never accepted, but in 2019 was partially implemented by Synapse[^1]: it was only implemented for the client-server endpoints, and an error code of `M_FORBIDDEN` was used rather than `M_USER_NOT_PUBLIC`. In 2021, Synapse implemented[^2] a switchable feature to disable profile look-up over federation via a 403 `M_FORBIDDEN` response. [MSC3550] picked up on this feature and introduced this response type in the spec though only on the `GET /_matrix/client/v3/profile/{userId}` endpoint in the client-server API. ## Unstable prefix None because this proposal only affects HTTP status codes and Matrix error codes. ## Dependencies None. [^1]: https://github.com/element-hq/synapse/commit/c0e0740bef0db661abce352afaf6c958e276f11d [^2]: https://github.com/matrix-org/synapse/pull/9203/files#diff-2f70c35b9dd342bfdaaed445847e0ccabbad63aa9a208d80d38fb248cbf57602L311 [^3]: As stated in https://github.com/matrix-org/matrix-spec/issues/633, the spec currently doesn't clearly define what a public room is. This proposal does not aim to solve this problem and instead only requires that the user directory and profile APIs use the same definition. [`GET /_matrix/client/v3/profile/{userId}`]: https://spec.matrix.org/v1.11/client-server-api/#get_matrixclientv3profileuserid [`GET /_matrix/client/v3/profile/{userId}/avatar_url`]: https://spec.matrix.org/v1.11/client-server-api/#get_matrixclientv3profileuseridavatar_url [`GET /_matrix/client/v3/profile/{userId}/displayname`]: https://spec.matrix.org/v1.11/client-server-api/#get_matrixclientv3profileuseriddisplayname [`GET /_matrix/federation/v1/query/profile`]: https://spec.matrix.org/v1.11/server-server-api/#get_matrixfederationv1queryprofile [`POST /_matrix/client/v3/user_directory/search`]: https://spec.matrix.org/v1.11/client-server-api/#post_matrixclientv3user_directorysearch [2017]: https://github.com/matrix-org/matrix-spec-proposals/pull/1096/files#diff-332ce28a7277b9375050644632f99c0e606acb751adc54c64c5faabf981ac7edR35 [MSC1301]: https://github.com/matrix-org/matrix-spec-proposals/issues/1301 [MSC3550]: https://github.com/matrix-org/matrix-spec-proposals/pull/3550 [client-server APIs]: https://spec.matrix.org/v1.11/client-server-api/#profiles [server-server API]: https://spec.matrix.org/v1.11/server-server-api/#get_matrixfederationv1queryprofile