matrix-org / matrix-org/matrix-spec
"Requires authentication" phrasing can be confusing
- Dominant language
- HTML
- Stars
- 330
- Forks
- 150
- Avg merge
- 2h 21m
- Merged PRs (30d)
- 3
Description
**Link to problem area**: https://spec.matrix.org/v1.10/client-server-api/#post_matrixclientv3accountpassword or https://spec.matrix.org/v1.10/client-server-api/#post_matrixclientv3accountdeactivate, for example, but it will be clearer in v1.11.
**Issue**
As brought up in https://github.com/matrix-org/matrix-spec/pull/1843#issuecomment-2176362807, the "Requires authentication" line for endpoints is only for whether an access token is required or not. However some endpoints like `/password` and `/deactivate` do not require an access token but require authentication via UIAA.
The phrasing could be changed to something like "Requires access token", for example.
Contributor guide
Research direction
Start with the linked password and deactivate endpoint sections in the Matrix client-server API specification and search the specification for the “Requires authentication” label. Update the phrasing so it describes access-token requirements without confusing endpoints that use UIAA, then verify the affected endpoint documentation reads consistently.
Written by the indexing model from the issue text.
Assessment
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Stale
- Clarity
- Clearly specified
- Newbie friendliness
- 65/100