Skip to content
This repository has been archived by the owner on Apr 26, 2024. It is now read-only.

Add warnings about MSC3861 on certain APIs. #16168

Merged
merged 2 commits into from
Aug 25, 2023
Merged

Add warnings about MSC3861 on certain APIs. #16168

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
a7a9601
Add warnings about MSC3861 on certain APIs.
Half-Shot Aug 23, 2023
f63a909
Add newsfragment
clokep Aug 25, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions changelog.d/16168.doc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
Document which admin APIs are disabled when experimental [MSC3861](https://github.com/matrix-org/matrix-spec-proposals/pull/3861) support is enabled.
2 changes: 2 additions & 0 deletions docs/admin_api/account_validity.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
# Account validity API

**Note:** This API is disabled when MSC3861 is enabled. [See #15582](https://github.com/matrix-org/synapse/pull/15582)
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think linking off to the pull request is likely not super helpful for end-users.

It is a bit odd though because this is an experimental feature which we don't really document. I'm not quite sure what to do about this. (It does seem valuable...)

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agree with the sentiment that documenting experimental is quite unusual, but equally I worry we're expecting people to start using OIDC with Element X imminently and need to document what may break.

I mean, in an ideal world we'd have gone through and made OIDC stable before asking people to use it in production.


This API allows a server administrator to manage the validity of an account. To
use it, you must enable the account validity feature (under
`account_validity`) in Synapse's configuration.
Expand Down
2 changes: 2 additions & 0 deletions docs/admin_api/register_api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
# Shared-Secret Registration

**Note:** This API is disabled when MSC3861 is enabled. [See #15582](https://github.com/matrix-org/synapse/pull/15582)

This API allows for the creation of users in an administrative and
non-interactive way. This is generally used for bootstrapping a Synapse
instance with administrator accounts.
Expand Down
10 changes: 9 additions & 1 deletion docs/admin_api/user_admin_api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -218,7 +218,7 @@ The following parameters should be set in the URL:
- `name` - Is optional and filters to only return users with user ID localparts
**or** displaynames that contain this value.
- `guests` - string representing a bool - Is optional and if `false` will **exclude** guest users.
Defaults to `true` to include guest users.
Defaults to `true` to include guest users. This parameter is not supported when MSC3861 is enabled. [See #15582](https://github.com/matrix-org/synapse/pull/15582)
- `admins` - Optional flag to filter admins. If `true`, only admins are queried. If `false`, admins are excluded from
the query. When the flag is absent (the default), **both** admins and non-admins are included in the search results.
- `deactivated` - string representing a bool - Is optional and if `true` will **include** deactivated users.
Expand Down Expand Up @@ -390,6 +390,8 @@ The following actions are **NOT** performed. The list may be incomplete.

## Reset password

**Note:** This API is disabled when MSC3861 is enabled. [See #15582](https://github.com/matrix-org/synapse/pull/15582)

Changes the password of another user. This will automatically log the user out of all their devices.

The api is:
Expand All @@ -413,6 +415,8 @@ The parameter `logout_devices` is optional and defaults to `true`.

## Get whether a user is a server administrator or not

**Note:** This API is disabled when MSC3861 is enabled. [See #15582](https://github.com/matrix-org/synapse/pull/15582)

The api is:

```
Expand All @@ -430,6 +434,8 @@ A response body like the following is returned:

## Change whether a user is a server administrator or not

**Note:** This API is disabled when MSC3861 is enabled. [See #15582](https://github.com/matrix-org/synapse/pull/15582)

Note that you cannot demote yourself.

The api is:
Expand Down Expand Up @@ -723,6 +729,8 @@ delete largest/smallest or newest/oldest files first.

## Login as a user

**Note:** This API is disabled when MSC3861 is enabled. [See #15582](https://github.com/matrix-org/synapse/pull/15582)

Get an access token that can be used to authenticate as that user. Useful for
when admins wish to do actions on behalf of a user.

Expand Down
2 changes: 2 additions & 0 deletions docs/usage/administration/admin_api/registration_tokens.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
# Registration Tokens

**Note:** This API is disabled when MSC3861 is enabled. [See #15582](https://github.com/matrix-org/synapse/pull/15582)

This API allows you to manage tokens which can be used to authenticate
registration requests, as proposed in
[MSC3231](https://github.com/matrix-org/matrix-doc/blob/main/proposals/3231-token-authenticated-registration.md)
Expand Down
Loading