# 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
