diff --git a/latest/print.html b/latest/print.html
index 00e2e78cc7..9e04941d39 100644
--- a/latest/print.html
+++ b/latest/print.html
@@ -101,7 +101,7 @@
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
<div class="sidebar-scrollbox">
- <ol class="chapter"><li class="chapter-item expanded affix "><li class="part-title">Introduction</li><li class="chapter-item expanded "><a href="welcome_and_overview.html">Welcome and Overview</a></li><li class="chapter-item expanded affix "><li class="part-title">Setup</li><li class="chapter-item expanded "><a href="setup/installation.html">Installation</a></li><li class="chapter-item expanded "><a href="postgres.html">Using Postgres</a></li><li class="chapter-item expanded "><a href="reverse_proxy.html">Configuring a Reverse Proxy</a></li><li class="chapter-item expanded "><a href="setup/forward_proxy.html">Configuring a Forward/Outbound Proxy</a></li><li class="chapter-item expanded "><a href="turn-howto.html">Configuring a Turn Server</a></li><li class="chapter-item expanded "><a href="delegate.html">Delegation</a></li><li class="chapter-item expanded affix "><li class="part-title">Upgrading</li><li class="chapter-item expanded "><a href="upgrade.html">Upgrading between Synapse Versions</a></li><li class="chapter-item expanded "><a href="MSC1711_certificates_FAQ.html">Upgrading from pre-Synapse 1.0</a></li><li class="chapter-item expanded affix "><li class="part-title">Usage</li><li class="chapter-item expanded "><a href="federate.html">Federation</a></li><li class="chapter-item expanded "><a href="usage/configuration/index.html">Configuration</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="usage/configuration/homeserver_sample_config.html">Homeserver Sample Config File</a></li><li class="chapter-item expanded "><a href="usage/configuration/logging_sample_config.html">Logging Sample Config File</a></li><li class="chapter-item expanded "><a href="structured_logging.html">Structured Logging</a></li><li class="chapter-item expanded "><a href="templates.html">Templates</a></li><li class="chapter-item expanded "><a href="usage/configuration/user_authentication/index.html">User Authentication</a></li><li><ol class="section"><li class="chapter-item expanded "><div>Single-Sign On</div></li><li><ol class="section"><li class="chapter-item expanded "><a href="openid.html">OpenID Connect</a></li><li class="chapter-item expanded "><div>SAML</div></li><li class="chapter-item expanded "><div>CAS</div></li><li class="chapter-item expanded "><a href="sso_mapping_providers.html">SSO Mapping Providers</a></li></ol></li><li class="chapter-item expanded "><a href="password_auth_providers.html">Password Auth Providers</a></li><li class="chapter-item expanded "><a href="jwt.html">JSON Web Tokens</a></li></ol></li><li class="chapter-item expanded "><a href="CAPTCHA_SETUP.html">Registration Captcha</a></li><li class="chapter-item expanded "><a href="application_services.html">Application Services</a></li><li class="chapter-item expanded "><a href="server_notices.html">Server Notices</a></li><li class="chapter-item expanded "><a href="consent_tracking.html">Consent Tracking</a></li><li class="chapter-item expanded "><a href="development/url_previews.html">URL Previews</a></li><li class="chapter-item expanded "><a href="user_directory.html">User Directory</a></li><li class="chapter-item expanded "><a href="message_retention_policies.html">Message Retention Policies</a></li><li class="chapter-item expanded "><a href="modules/index.html">Pluggable Modules</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="modules/writing_a_module.html">Writing a module</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="modules/spam_checker_callbacks.html">Spam checker callbacks</a></li><li class="chapter-item expanded "><a href="modules/third_party_rules_callbacks.html">Third-party rules callbacks</a></li><li class="chapter-item expanded "><a href="modules/presence_router_callbacks.html">Presence router callbacks</a></li><li class="chapter-item expanded "><a href="modules/account_validity_callbacks.html">Account validity callbacks</a></li><li class="chapter-item expanded "><a href="modules/password_auth_provider_callbacks.html">Password auth provider callbacks</a></li><li class="chapter-item expanded "><a href="modules/porting_legacy_module.html">Porting a legacy module to the new interface</a></li></ol></li></ol></li><li class="chapter-item expanded "><a href="workers.html">Workers</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="synctl_workers.html">Using synctl with Workers</a></li><li class="chapter-item expanded "><a href="systemd-with-workers/index.html">Systemd</a></li></ol></li></ol></li><li class="chapter-item expanded "><a href="usage/administration/index.html">Administration</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="usage/administration/admin_api/index.html">Admin API</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="admin_api/account_validity.html">Account Validity</a></li><li class="chapter-item expanded "><a href="usage/administration/admin_api/background_updates.html">Background Updates</a></li><li class="chapter-item expanded "><a href="admin_api/delete_group.html">Delete Group</a></li><li class="chapter-item expanded "><a href="admin_api/event_reports.html">Event Reports</a></li><li class="chapter-item expanded "><a href="admin_api/media_admin_api.html">Media</a></li><li class="chapter-item expanded "><a href="admin_api/purge_history_api.html">Purge History</a></li><li class="chapter-item expanded "><a href="admin_api/register_api.html">Register Users</a></li><li class="chapter-item expanded "><a href="usage/administration/admin_api/registration_tokens.html">Registration Tokens</a></li><li class="chapter-item expanded "><a href="admin_api/room_membership.html">Manipulate Room Membership</a></li><li class="chapter-item expanded "><a href="admin_api/rooms.html">Rooms</a></li><li class="chapter-item expanded "><a href="admin_api/server_notices.html">Server Notices</a></li><li class="chapter-item expanded "><a href="admin_api/statistics.html">Statistics</a></li><li class="chapter-item expanded "><a href="admin_api/user_admin_api.html">Users</a></li><li class="chapter-item expanded "><a href="admin_api/version_api.html">Server Version</a></li></ol></li><li class="chapter-item expanded "><a href="manhole.html">Manhole</a></li><li class="chapter-item expanded "><a href="metrics-howto.html">Monitoring</a></li><li class="chapter-item expanded "><a href="usage/administration/request_log.html">Request log format</a></li><li class="chapter-item expanded "><div>Scripts</div></li></ol></li><li class="chapter-item expanded "><li class="part-title">Development</li><li class="chapter-item expanded "><a href="development/contributing_guide.html">Contributing Guide</a></li><li class="chapter-item expanded "><a href="code_style.html">Code Style</a></li><li class="chapter-item expanded "><a href="development/git.html">Git Usage</a></li><li class="chapter-item expanded "><div>Testing</div></li><li class="chapter-item expanded "><a href="opentracing.html">OpenTracing</a></li><li class="chapter-item expanded "><a href="development/database_schema.html">Database Schemas</a></li><li class="chapter-item expanded "><a href="development/experimental_features.html">Experimental features</a></li><li class="chapter-item expanded "><div>Synapse Architecture</div></li><li><ol class="section"><li class="chapter-item expanded "><a href="log_contexts.html">Log Contexts</a></li><li class="chapter-item expanded "><a href="replication.html">Replication</a></li><li class="chapter-item expanded "><a href="tcp_replication.html">TCP Replication</a></li></ol></li><li class="chapter-item expanded "><a href="development/internal_documentation/index.html">Internal Documentation</a></li><li><ol class="section"><li class="chapter-item expanded "><div>Single Sign-On</div></li><li><ol class="section"><li class="chapter-item expanded "><a href="development/saml.html">SAML</a></li><li class="chapter-item expanded "><a href="development/cas.html">CAS</a></li></ol></li><li class="chapter-item expanded "><a href="development/room-dag-concepts.html">Room DAG concepts</a></li><li class="chapter-item expanded "><div>State Resolution</div></li><li><ol class="section"><li class="chapter-item expanded "><a href="auth_chain_difference_algorithm.html">The Auth Chain Difference Algorithm</a></li></ol></li><li class="chapter-item expanded "><a href="media_repository.html">Media Repository</a></li><li class="chapter-item expanded "><a href="room_and_user_statistics.html">Room and User Statistics</a></li></ol></li><li class="chapter-item expanded "><div>Scripts</div></li><li class="chapter-item expanded affix "><li class="part-title">Other</li><li class="chapter-item expanded "><a href="deprecation_policy.html">Dependency Deprecation Policy</a></li></ol>
+ <ol class="chapter"><li class="chapter-item expanded affix "><li class="part-title">Introduction</li><li class="chapter-item expanded "><a href="welcome_and_overview.html">Welcome and Overview</a></li><li class="chapter-item expanded affix "><li class="part-title">Setup</li><li class="chapter-item expanded "><a href="setup/installation.html">Installation</a></li><li class="chapter-item expanded "><a href="postgres.html">Using Postgres</a></li><li class="chapter-item expanded "><a href="reverse_proxy.html">Configuring a Reverse Proxy</a></li><li class="chapter-item expanded "><a href="setup/forward_proxy.html">Configuring a Forward/Outbound Proxy</a></li><li class="chapter-item expanded "><a href="turn-howto.html">Configuring a Turn Server</a></li><li class="chapter-item expanded "><a href="delegate.html">Delegation</a></li><li class="chapter-item expanded affix "><li class="part-title">Upgrading</li><li class="chapter-item expanded "><a href="upgrade.html">Upgrading between Synapse Versions</a></li><li class="chapter-item expanded "><a href="MSC1711_certificates_FAQ.html">Upgrading from pre-Synapse 1.0</a></li><li class="chapter-item expanded affix "><li class="part-title">Usage</li><li class="chapter-item expanded "><a href="federate.html">Federation</a></li><li class="chapter-item expanded "><a href="usage/configuration/index.html">Configuration</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="usage/configuration/homeserver_sample_config.html">Homeserver Sample Config File</a></li><li class="chapter-item expanded "><a href="usage/configuration/logging_sample_config.html">Logging Sample Config File</a></li><li class="chapter-item expanded "><a href="structured_logging.html">Structured Logging</a></li><li class="chapter-item expanded "><a href="templates.html">Templates</a></li><li class="chapter-item expanded "><a href="usage/configuration/user_authentication/index.html">User Authentication</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="usage/configuration/user_authentication/single_sign_on/index.html">Single-Sign On</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="openid.html">OpenID Connect</a></li><li class="chapter-item expanded "><a href="usage/configuration/user_authentication/single_sign_on/saml.html">SAML</a></li><li class="chapter-item expanded "><a href="usage/configuration/user_authentication/single_sign_on/cas.html">CAS</a></li><li class="chapter-item expanded "><a href="sso_mapping_providers.html">SSO Mapping Providers</a></li></ol></li><li class="chapter-item expanded "><a href="password_auth_providers.html">Password Auth Providers</a></li><li class="chapter-item expanded "><a href="jwt.html">JSON Web Tokens</a></li></ol></li><li class="chapter-item expanded "><a href="CAPTCHA_SETUP.html">Registration Captcha</a></li><li class="chapter-item expanded "><a href="application_services.html">Application Services</a></li><li class="chapter-item expanded "><a href="server_notices.html">Server Notices</a></li><li class="chapter-item expanded "><a href="consent_tracking.html">Consent Tracking</a></li><li class="chapter-item expanded "><a href="development/url_previews.html">URL Previews</a></li><li class="chapter-item expanded "><a href="user_directory.html">User Directory</a></li><li class="chapter-item expanded "><a href="message_retention_policies.html">Message Retention Policies</a></li><li class="chapter-item expanded "><a href="modules/index.html">Pluggable Modules</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="modules/writing_a_module.html">Writing a module</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="modules/spam_checker_callbacks.html">Spam checker callbacks</a></li><li class="chapter-item expanded "><a href="modules/third_party_rules_callbacks.html">Third-party rules callbacks</a></li><li class="chapter-item expanded "><a href="modules/presence_router_callbacks.html">Presence router callbacks</a></li><li class="chapter-item expanded "><a href="modules/account_validity_callbacks.html">Account validity callbacks</a></li><li class="chapter-item expanded "><a href="modules/password_auth_provider_callbacks.html">Password auth provider callbacks</a></li><li class="chapter-item expanded "><a href="modules/porting_legacy_module.html">Porting a legacy module to the new interface</a></li></ol></li></ol></li><li class="chapter-item expanded "><a href="workers.html">Workers</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="synctl_workers.html">Using synctl with Workers</a></li><li class="chapter-item expanded "><a href="systemd-with-workers/index.html">Systemd</a></li></ol></li></ol></li><li class="chapter-item expanded "><a href="usage/administration/index.html">Administration</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="usage/administration/admin_api/index.html">Admin API</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="admin_api/account_validity.html">Account Validity</a></li><li class="chapter-item expanded "><a href="usage/administration/admin_api/background_updates.html">Background Updates</a></li><li class="chapter-item expanded "><a href="admin_api/delete_group.html">Delete Group</a></li><li class="chapter-item expanded "><a href="admin_api/event_reports.html">Event Reports</a></li><li class="chapter-item expanded "><a href="admin_api/media_admin_api.html">Media</a></li><li class="chapter-item expanded "><a href="admin_api/purge_history_api.html">Purge History</a></li><li class="chapter-item expanded "><a href="admin_api/register_api.html">Register Users</a></li><li class="chapter-item expanded "><a href="usage/administration/admin_api/registration_tokens.html">Registration Tokens</a></li><li class="chapter-item expanded "><a href="admin_api/room_membership.html">Manipulate Room Membership</a></li><li class="chapter-item expanded "><a href="admin_api/rooms.html">Rooms</a></li><li class="chapter-item expanded "><a href="admin_api/server_notices.html">Server Notices</a></li><li class="chapter-item expanded "><a href="admin_api/statistics.html">Statistics</a></li><li class="chapter-item expanded "><a href="admin_api/user_admin_api.html">Users</a></li><li class="chapter-item expanded "><a href="admin_api/version_api.html">Server Version</a></li></ol></li><li class="chapter-item expanded "><a href="manhole.html">Manhole</a></li><li class="chapter-item expanded "><a href="metrics-howto.html">Monitoring</a></li><li class="chapter-item expanded "><a href="usage/administration/request_log.html">Request log format</a></li><li class="chapter-item expanded "><div>Scripts</div></li></ol></li><li class="chapter-item expanded "><li class="part-title">Development</li><li class="chapter-item expanded "><a href="development/contributing_guide.html">Contributing Guide</a></li><li class="chapter-item expanded "><a href="code_style.html">Code Style</a></li><li class="chapter-item expanded "><a href="development/git.html">Git Usage</a></li><li class="chapter-item expanded "><div>Testing</div></li><li class="chapter-item expanded "><a href="opentracing.html">OpenTracing</a></li><li class="chapter-item expanded "><a href="development/database_schema.html">Database Schemas</a></li><li class="chapter-item expanded "><a href="development/experimental_features.html">Experimental features</a></li><li class="chapter-item expanded "><div>Synapse Architecture</div></li><li><ol class="section"><li class="chapter-item expanded "><a href="log_contexts.html">Log Contexts</a></li><li class="chapter-item expanded "><a href="replication.html">Replication</a></li><li class="chapter-item expanded "><a href="tcp_replication.html">TCP Replication</a></li></ol></li><li class="chapter-item expanded "><a href="development/internal_documentation/index.html">Internal Documentation</a></li><li><ol class="section"><li class="chapter-item expanded "><div>Single Sign-On</div></li><li><ol class="section"><li class="chapter-item expanded "><a href="development/saml.html">SAML</a></li><li class="chapter-item expanded "><a href="development/cas.html">CAS</a></li></ol></li><li class="chapter-item expanded "><a href="development/room-dag-concepts.html">Room DAG concepts</a></li><li class="chapter-item expanded "><div>State Resolution</div></li><li><ol class="section"><li class="chapter-item expanded "><a href="auth_chain_difference_algorithm.html">The Auth Chain Difference Algorithm</a></li></ol></li><li class="chapter-item expanded "><a href="media_repository.html">Media Repository</a></li><li class="chapter-item expanded "><a href="room_and_user_statistics.html">Room and User Statistics</a></li></ol></li><li class="chapter-item expanded "><div>Scripts</div></li><li class="chapter-item expanded affix "><li class="part-title">Other</li><li class="chapter-item expanded "><a href="deprecation_policy.html">Dependency Deprecation Policy</a></li></ol>
</div>
<div id="sidebar-resize-handle" class="sidebar-resize-handle"></div>
</nav>
@@ -320,6 +320,11 @@ sudo apt install matrix-synapse-py3
</code></pre>
<p>The fingerprint of the repository signing key (as shown by <code>gpg /usr/share/keyrings/matrix-org-archive-keyring.gpg</code>) is
<code>AAF9AE843A7584B5A3E4CD2BCF45A512DE2DA058</code>.</p>
+<p>When installing with Debian packages, you might prefer to place files in
+<code>/etc/matrix-synapse/conf.d/</code> to override your configuration without editing
+the main configuration file at <code>/etc/matrix-synapse/homeserver.yaml</code>.
+By doing that, you won't be asked if you want to replace your configuration
+file when you upgrade the Debian package to a later version.</p>
<h5 id="downstream-debian-packages"><a class="header" href="#downstream-debian-packages">Downstream Debian packages</a></h5>
<p>We do not recommend using the packages from the default Debian <code>buster</code>
repository at this time, as they are old and suffer from known security
@@ -1162,12 +1167,12 @@ in Synapse can be deactivated.</p>
<pre><code class="language-yaml">use_insecure_ssl_client_just_for_testing_do_not_use: true
</code></pre>
<div id="chapter_begin" style="break-before: page; page-break-before: always;"></div><h1 id="overview-1"><a class="header" href="#overview-1">Overview</a></h1>
-<p>This document explains how to enable VoIP relaying on your Home Server with
+<p>This document explains how to enable VoIP relaying on your homeserver with
TURN.</p>
-<p>The synapse Matrix Home Server supports integration with TURN server via the
+<p>The synapse Matrix homeserver supports integration with TURN server via the
<a href="https://tools.ietf.org/html/draft-uberti-behave-turn-rest-00">TURN server REST API</a>. This
-allows the Home Server to generate credentials that are valid for use on the
-TURN server through the use of a secret shared between the Home Server and the
+allows the homeserver to generate credentials that are valid for use on the
+TURN server through the use of a secret shared between the homeserver and the
TURN server.</p>
<p>The following sections describe how to install <a href="https://github.com/coturn/coturn">coturn</a> (which implements the TURN REST API) and integrate it with synapse.</p>
<h2 id="requirements"><a class="header" href="#requirements">Requirements</a></h2>
@@ -1300,18 +1305,18 @@ external IP address:</p>
</li>
</ol>
<h2 id="synapse-setup"><a class="header" href="#synapse-setup">Synapse setup</a></h2>
-<p>Your home server configuration file needs the following extra keys:</p>
+<p>Your homeserver configuration file needs the following extra keys:</p>
<ol>
<li>"<code>turn_uris</code>": This needs to be a yaml list of public-facing URIs
for your TURN server to be given out to your clients. Add separate
entries for each transport your TURN server supports.</li>
<li>"<code>turn_shared_secret</code>": This is the secret shared between your
-Home server and your TURN server, so you should set it to the same
+homeserver and your TURN server, so you should set it to the same
string you used in turnserver.conf.</li>
<li>"<code>turn_user_lifetime</code>": This is the amount of time credentials
-generated by your Home Server are valid for (in milliseconds).
+generated by your homeserver are valid for (in milliseconds).
Shorter times offer less potential for abuse at the expense of
-increased traffic between web clients and your home server to
+increased traffic between web clients and your homeserver to
refresh credentials. The TURN REST API specification recommends
one day (86400000).</li>
<li>"<code>turn_allow_guests</code>": Whether to allow guest users to use the
@@ -3710,8 +3715,8 @@ retention:
#
#federation_certificate_verification_whitelist:
# - lon.example.com
-# - *.domain.com
-# - *.onion
+# - "*.domain.com"
+# - "*.onion"
# List of custom certificate authorities for federation traffic.
#
@@ -5102,6 +5107,12 @@ sso:
#
#algorithm: "provided-by-your-issuer"
+ # Name of the claim containing a unique identifier for the user.
+ #
+ # Optional, defaults to `sub`.
+ #
+ #subject_claim: "sub"
+
# The issuer to validate the "iss" claim against.
#
# Optional, if provided the "iss" claim will be required and
@@ -5423,8 +5434,8 @@ user_directory:
# indexes were (re)built was before Synapse 1.44, you'll have to
# rebuild the indexes in order to search through all known users.
# These indexes are built the first time Synapse starts; admins can
- # manually trigger a rebuild following the instructions at
- # https://matrix-org.github.io/synapse/latest/user_directory.html
+ # manually trigger a rebuild via API following the instructions at
+ # https://matrix-org.github.io/synapse/latest/usage/administration/admin_api/background_updates.html#run
#
# Uncomment to return search results containing all known users, even if that
# user does not share a room with the requester.
@@ -6218,6 +6229,10 @@ authentication modules.</p>
</ul>
<p>Synapse can additionally be extended to support custom authentication schemes through optional "password auth provider"
modules.</p>
+<div id="chapter_begin" style="break-before: page; page-break-before: always;"></div><h1 id="single-sign-on"><a class="header" href="#single-sign-on">Single Sign-On</a></h1>
+<p>Synapse supports single sign-on through the SAML, Open ID Connect or CAS protocols.
+LDAP and other login methods are supported through first and third-party password
+auth provider modules.</p>
<div id="chapter_begin" style="break-before: page; page-break-before: always;"></div><h1 id="configuring-synapse-to-authenticate-against-an-openid-connect-provider"><a class="header" href="#configuring-synapse-to-authenticate-against-an-openid-connect-provider">Configuring Synapse to authenticate against an OpenID Connect provider</a></h1>
<p>Synapse can be configured to use an OpenID Connect Provider (OP) for
authentication, instead of its own local password database.</p>
@@ -6735,6 +6750,18 @@ needed to add OAuth2 capabilities to your Django projects. It supports
display_name_template: "{{ user.first_name }} {{ user.last_name }}"
email_template: "{{ user.email }}"
</code></pre>
+<div id="chapter_begin" style="break-before: page; page-break-before: always;"></div><h1 id="saml"><a class="header" href="#saml">SAML</a></h1>
+<p>Synapse supports authenticating users via the <a href="https://en.wikipedia.org/wiki/Security_Assertion_Markup_Language">Security Assertion
+Markup Language</a>
+(SAML) protocol natively.</p>
+<p>Please see the <code>saml2_config</code> and <code>sso</code> sections of the <a href="usage/configuration/user_authentication/single_sign_on/../../../configuration/homeserver_sample_config.html">Synapse configuration
+file</a> for more details.</p>
+<div id="chapter_begin" style="break-before: page; page-break-before: always;"></div><h1 id="cas"><a class="header" href="#cas">CAS</a></h1>
+<p>Synapse supports authenticating users via the <a href="https://en.wikipedia.org/wiki/Central_Authentication_Service">Central Authentication
+Service protocol</a>
+(CAS) natively.</p>
+<p>Please see the <code>cas_config</code> and <code>sso</code> sections of the <a href="usage/configuration/user_authentication/single_sign_on/../../../configuration/homeserver_sample_config.html">Synapse configuration
+file</a> for more details.</p>
<div id="chapter_begin" style="break-before: page; page-break-before: always;"></div><h1 id="sso-mapping-providers"><a class="header" href="#sso-mapping-providers">SSO Mapping Providers</a></h1>
<p>A mapping provider is a Python class (loaded via a Python module) that
works out how to map attributes of a SSO response to Matrix-specific
@@ -7116,8 +7143,9 @@ follows:</p>
will be removed in a future version of Synapse.</p>
<p>The <code>token</code> field should include the JSON web token with the following claims:</p>
<ul>
-<li>The <code>sub</code> (subject) claim is required and should encode the local part of the
-user ID.</li>
+<li>A claim that encodes the local part of the user ID is required. By default,
+the <code>sub</code> (subject) claim is used, or a custom claim can be set in the
+configuration file.</li>
<li>The expiration time (<code>exp</code>), not before time (<code>nbf</code>), and issued at (<code>iat</code>)
claims are optional, but validated if present.</li>
<li>The issuer (<code>iss</code>) claim is optional, but required and validated if configured.</li>
@@ -7534,9 +7562,9 @@ deleted every 10 seconds. The default expiration time is 1 hour from download.</
on this particular server - i.e. ones which your account shares a room with, or
who are present in a publicly viewable room present on the server.</p>
<p>The directory info is stored in various tables, which can (typically after
-DB corruption) get stale or out of sync. If this happens, for now the
-solution to fix it is to execute the SQL <a href="https://github.com/matrix-org/synapse/blob/master/synapse/storage/schema/main/delta/53/user_dir_populate.sql">here</a>
-and then restart synapse. This should then start a background task to
+DB corruption) get stale or out of sync. If this happens, for now the
+solution to fix it is to use the <a href="usage/administration/admin_api/background_updates.html#run">admin API</a>
+and execute the job <code>regenerate_directory</code>. This should then start a background task to
flush the current tables and regenerate the directory.</p>
<h2 id="data-model"><a class="header" href="#data-model">Data model</a></h2>
<p>There are five relevant tables that collectively form the "user directory".
@@ -8605,10 +8633,10 @@ recommend the use of <code>systemd</code> where available: for information on se
<p>This worker can handle API requests matching the following regular
expressions:</p>
<pre><code># Sync requests
-^/_matrix/client/(v2_alpha|r0)/sync$
-^/_matrix/client/(api/v1|v2_alpha|r0)/events$
-^/_matrix/client/(api/v1|r0)/initialSync$
-^/_matrix/client/(api/v1|r0)/rooms/[^/]+/initialSync$
+^/_matrix/client/(v2_alpha|r0|v3)/sync$
+^/_matrix/client/(api/v1|v2_alpha|r0|v3)/events$
+^/_matrix/client/(api/v1|r0|v3)/initialSync$
+^/_matrix/client/(api/v1|r0|v3)/rooms/[^/]+/initialSync$
# Federation requests
^/_matrix/federation/v1/event/
@@ -8639,40 +8667,40 @@ expressions:</p>
^/_matrix/federation/v1/send/
# Client API requests
-^/_matrix/client/(api/v1|r0|unstable)/createRoom$
-^/_matrix/client/(api/v1|r0|unstable)/publicRooms$
-^/_matrix/client/(api/v1|r0|unstable)/rooms/.*/joined_members$
-^/_matrix/client/(api/v1|r0|unstable)/rooms/.*/context/.*$
-^/_matrix/client/(api/v1|r0|unstable)/rooms/.*/members$
-^/_matrix/client/(api/v1|r0|unstable)/rooms/.*/state$
+^/_matrix/client/(api/v1|r0|v3|unstable)/createRoom$
+^/_matrix/client/(api/v1|r0|v3|unstable)/publicRooms$
+^/_matrix/client/(api/v1|r0|v3|unstable)/rooms/.*/joined_members$
+^/_matrix/client/(api/v1|r0|v3|unstable)/rooms/.*/context/.*$
+^/_matrix/client/(api/v1|r0|v3|unstable)/rooms/.*/members$
+^/_matrix/client/(api/v1|r0|v3|unstable)/rooms/.*/state$
^/_matrix/client/unstable/org.matrix.msc2946/rooms/.*/spaces$
^/_matrix/client/unstable/org.matrix.msc2946/rooms/.*/hierarchy$
^/_matrix/client/unstable/im.nheko.summary/rooms/.*/summary$
-^/_matrix/client/(api/v1|r0|unstable)/account/3pid$
-^/_matrix/client/(api/v1|r0|unstable)/devices$
-^/_matrix/client/(api/v1|r0|unstable)/keys/query$
-^/_matrix/client/(api/v1|r0|unstable)/keys/changes$
+^/_matrix/client/(api/v1|r0|v3|unstable)/account/3pid$
+^/_matrix/client/(api/v1|r0|v3|unstable)/devices$
+^/_matrix/client/(api/v1|r0|v3|unstable)/keys/query$
+^/_matrix/client/(api/v1|r0|v3|unstable)/keys/changes$
^/_matrix/client/versions$
-^/_matrix/client/(api/v1|r0|unstable)/voip/turnServer$
-^/_matrix/client/(api/v1|r0|unstable)/joined_groups$
-^/_matrix/client/(api/v1|r0|unstable)/publicised_groups$
-^/_matrix/client/(api/v1|r0|unstable)/publicised_groups/
-^/_matrix/client/(api/v1|r0|unstable)/rooms/.*/event/
-^/_matrix/client/(api/v1|r0|unstable)/joined_rooms$
-^/_matrix/client/(api/v1|r0|unstable)/search$
+^/_matrix/client/(api/v1|r0|v3|unstable)/voip/turnServer$
+^/_matrix/client/(api/v1|r0|v3|unstable)/joined_groups$
+^/_matrix/client/(api/v1|r0|v3|unstable)/publicised_groups$
+^/_matrix/client/(api/v1|r0|v3|unstable)/publicised_groups/
+^/_matrix/client/(api/v1|r0|v3|unstable)/rooms/.*/event/
+^/_matrix/client/(api/v1|r0|v3|unstable)/joined_rooms$
+^/_matrix/client/(api/v1|r0|v3|unstable)/search$
# Registration/login requests
-^/_matrix/client/(api/v1|r0|unstable)/login$
-^/_matrix/client/(r0|unstable)/register$
+^/_matrix/client/(api/v1|r0|v3|unstable)/login$
+^/_matrix/client/(r0|v3|unstable)/register$
^/_matrix/client/unstable/org.matrix.msc3231/register/org.matrix.msc3231.login.registration_token/validity$
# Event sending requests
-^/_matrix/client/(api/v1|r0|unstable)/rooms/.*/redact
-^/_matrix/client/(api/v1|r0|unstable)/rooms/.*/send
-^/_matrix/client/(api/v1|r0|unstable)/rooms/.*/state/
-^/_matrix/client/(api/v1|r0|unstable)/rooms/.*/(join|invite|leave|ban|unban|kick)$
-^/_matrix/client/(api/v1|r0|unstable)/join/
-^/_matrix/client/(api/v1|r0|unstable)/profile/
+^/_matrix/client/(api/v1|r0|v3|unstable)/rooms/.*/redact
+^/_matrix/client/(api/v1|r0|v3|unstable)/rooms/.*/send
+^/_matrix/client/(api/v1|r0|v3|unstable)/rooms/.*/state/
+^/_matrix/client/(api/v1|r0|v3|unstable)/rooms/.*/(join|invite|leave|ban|unban|kick)$
+^/_matrix/client/(api/v1|r0|v3|unstable)/join/
+^/_matrix/client/(api/v1|r0|v3|unstable)/profile/
</code></pre>
<p>Additionally, the following REST endpoints can be handled for GET requests:</p>
<pre><code>^/_matrix/federation/v1/groups/
@@ -8681,13 +8709,13 @@ expressions:</p>
room must be routed to the same instance. Additionally, care must be taken to
ensure that the purge history admin API is not used while pagination requests
for the room are in flight:</p>
-<pre><code>^/_matrix/client/(api/v1|r0|unstable)/rooms/.*/messages$
+<pre><code>^/_matrix/client/(api/v1|r0|v3|unstable)/rooms/.*/messages$
</code></pre>
<p>Additionally, the following endpoints should be included if Synapse is configured
to use SSO (you only need to include the ones for whichever SSO provider you're
using):</p>
<pre><code># for all SSO providers
-^/_matrix/client/(api/v1|r0|unstable)/login/sso/redirect
+^/_matrix/client/(api/v1|r0|v3|unstable)/login/sso/redirect
^/_synapse/client/pick_idp$
^/_synapse/client/pick_username
^/_synapse/client/new_user_consent$
@@ -8700,7 +8728,7 @@ using):</p>
^/_synapse/client/saml2/authn_response$
# CAS requests.
-^/_matrix/client/(api/v1|r0|unstable)/login/cas/ticket$
+^/_matrix/client/(api/v1|r0|v3|unstable)/login/cas/ticket$
</code></pre>
<p>Ensure that all SSO logins go to a single process.
For multiple workers not handling the SSO endpoints properly, see
@@ -8832,7 +8860,7 @@ and you must configure a single instance to run the background tasks, e.g.:</p>
<h3 id="synapseappuser_dir"><a class="header" href="#synapseappuser_dir"><code>synapse.app.user_dir</code></a></h3>
<p>Handles searches in the user directory. It can handle REST endpoints matching
the following regular expressions:</p>
-<pre><code>^/_matrix/client/(api/v1|r0|unstable)/user_directory/search$
+<pre><code>^/_matrix/client/(api/v1|r0|v3|unstable)/user_directory/search$
</code></pre>
<p>When using this worker you must also set <code>update_user_directory: False</code> in the
shared configuration file to stop the main synapse running background
@@ -8841,11 +8869,11 @@ jobs related to updating the user directory.</p>
<p>Proxies some frequently-requested client endpoints to add caching and remove
load from the main synapse. It can handle REST endpoints matching the following
regular expressions:</p>
-<pre><code>^/_matrix/client/(api/v1|r0|unstable)/keys/upload
+<pre><code>^/_matrix/client/(api/v1|r0|v3|unstable)/keys/upload
</code></pre>
<p>If <code>use_presence</code> is False in the homeserver config, it can also handle REST
endpoints matching the following regular expressions:</p>
-<pre><code>^/_matrix/client/(api/v1|r0|unstable)/presence/[^/]+/status
+<pre><code>^/_matrix/client/(api/v1|r0|v3|unstable)/presence/[^/]+/status
</code></pre>
<p>This "stub" presence handler will pass through <code>GET</code> request but make the
<code>PUT</code> effectively a no-op.</p>
@@ -9124,6 +9152,25 @@ background updates which won't be cancelled once started.</p>
}
</code></pre>
<p>There is also a <code>GET</code> version which returns the <code>enabled</code> state.</p>
+<h2 id="run"><a class="header" href="#run">Run</a></h2>
+<p>This API schedules a specific background update to run. The job starts immediately after calling the API.</p>
+<p>The API is:</p>
+<pre><code>POST /_synapse/admin/v1/background_updates/start_job
+</code></pre>
+<p>with the following body:</p>
+<pre><code class="language-json">{
+ "job_name": "populate_stats_process_rooms"
+}
+</code></pre>
+<p>The following JSON body parameters are available:</p>
+<ul>
+<li><code>job_name</code> - A string which job to run. Valid values are:
+<ul>
+<li><code>populate_stats_process_rooms</code> - Recalculate the stats for all rooms.</li>
+<li><code>regenerate_directory</code> - Recalculate the <a href="usage/administration/admin_api/../../../user_directory.html">user directory</a> if it is stale or out of sync.</li>
+</ul>
+</li>
+</ul>
<div id="chapter_begin" style="break-before: page; page-break-before: always;"></div><h1 id="delete-a-local-group"><a class="header" href="#delete-a-local-group">Delete a local group</a></h1>
<p>This API lets a server admin delete a local group. Doing so will kick all
users out of the group so that their clients will correctly handle the group
@@ -9574,6 +9621,7 @@ server admin.</p>
}
</code></pre>
<p>The status will be one of <code>active</code>, <code>complete</code>, or <code>failed</code>.</p>
+<p>If <code>status</code> is <code>failed</code> there will be a string <code>error</code> with the error message.</p>
<h2 id="reclaim-disk-space-postgres"><a class="header" href="#reclaim-disk-space-postgres">Reclaim disk space (Postgres)</a></h2>
<p>To reclaim the disk space and return it to the operating system, you need to run
<code>VACUUM FULL;</code> on the database.</p>
@@ -9909,8 +9957,12 @@ server admin: see <a href="admin_api/../usage/administration/admin_api">Admin AP
<li><a href="admin_api/rooms.html#room-details-api">Room Details API</a></li>
<li><a href="admin_api/rooms.html#room-members-api">Room Members API</a></li>
<li><a href="admin_api/rooms.html#room-state-api">Room State API</a></li>
+<li><a href="admin_api/rooms.html#block-room-api">Block Room API</a></li>
<li><a href="admin_api/rooms.html#delete-room-api">Delete Room API</a>
<ul>
+<li><a href="admin_api/rooms.html#version-1-old-version">Version 1 (old version)</a></li>
+<li><a href="admin_api/rooms.html#version-2-new-version">Version 2 (new version)</a></li>
+<li><a href="admin_api/rooms.html#status-of-deleting-rooms">Status of deleting rooms</a></li>
<li><a href="admin_api/rooms.html#undoing-room-shutdowns">Undoing room shutdowns</a></li>
</ul>
</li>
@@ -10257,6 +10309,61 @@ end of the list.</p>
]
}
</code></pre>
+<h1 id="block-room-api"><a class="header" href="#block-room-api">Block Room API</a></h1>
+<p>The Block Room admin API allows server admins to block and unblock rooms,
+and query to see if a given room is blocked.
+This API can be used to pre-emptively block a room, even if it's unknown to this
+homeserver. Users will be prevented from joining a blocked room.</p>
+<h2 id="block-or-unblock-a-room"><a class="header" href="#block-or-unblock-a-room">Block or unblock a room</a></h2>
+<p>The API is:</p>
+<pre><code>PUT /_synapse/admin/v1/rooms/<room_id>/block
+</code></pre>
+<p>with a body of:</p>
+<pre><code class="language-json">{
+ "block": true
+}
+</code></pre>
+<p>A response body like the following is returned:</p>
+<pre><code class="language-json">{
+ "block": true
+}
+</code></pre>
+<p><strong>Parameters</strong></p>
+<p>The following parameters should be set in the URL:</p>
+<ul>
+<li><code>room_id</code> - The ID of the room.</li>
+</ul>
+<p>The following JSON body parameters are available:</p>
+<ul>
+<li><code>block</code> - If <code>true</code> the room will be blocked and if <code>false</code> the room will be unblocked.</li>
+</ul>
+<p><strong>Response</strong></p>
+<p>The following fields are possible in the JSON response body:</p>
+<ul>
+<li><code>block</code> - A boolean. <code>true</code> if the room is blocked, otherwise <code>false</code></li>
+</ul>
+<h2 id="get-block-status"><a class="header" href="#get-block-status">Get block status</a></h2>
+<p>The API is:</p>
+<pre><code>GET /_synapse/admin/v1/rooms/<room_id>/block
+</code></pre>
+<p>A response body like the following is returned:</p>
+<pre><code class="language-json">{
+ "block": true,
+ "user_id": "<user_id>"
+}
+</code></pre>
+<p><strong>Parameters</strong></p>
+<p>The following parameters should be set in the URL:</p>
+<ul>
+<li><code>room_id</code> - The ID of the room.</li>
+</ul>
+<p><strong>Response</strong></p>
+<p>The following fields are possible in the JSON response body:</p>
+<ul>
+<li><code>block</code> - A boolean. <code>true</code> if the room is blocked, otherwise <code>false</code></li>
+<li><code>user_id</code> - An optional string. If the room is blocked (<code>block</code> is <code>true</code>) shows
+the user who has add the room to blocking list. Otherwise it is not displayed.</li>
+</ul>
<h1 id="delete-room-api"><a class="header" href="#delete-room-api">Delete Room API</a></h1>
<p>The Delete Room admin API allows server admins to remove rooms from the server
and block these rooms.</p>
@@ -10266,15 +10373,27 @@ leave the room without any information.</p>
<p>The new room will be created with the user specified by the <code>new_room_user_id</code> parameter
as room administrator and will contain a message explaining what happened. Users invited
to the new room will have power level <code>-10</code> by default, and thus be unable to speak.</p>
-<p>If <code>block</code> is <code>True</code> it prevents new joins to the old room.</p>
+<p>If <code>block</code> is <code>true</code>, users will be prevented from joining the old room.
+This option can in <a href="admin_api/rooms.html#version-1-old-version">Version 1</a> also be used to pre-emptively
+block a room, even if it's unknown to this homeserver. In this case, the room will be
+blocked, and no further action will be taken. If <code>block</code> is <code>false</code>, attempting to
+delete an unknown room is invalid and will be rejected as a bad request.</p>
<p>This API will remove all trace of the old room from your database after removing
all local users. If <code>purge</code> is <code>true</code> (the default), all traces of the old room will
be removed from your database after removing all local users. If you do not want
this to happen, set <code>purge</code> to <code>false</code>.
-Depending on the amount of history being purged a call to the API may take
+Depending on the amount of history being purged, a call to the API may take
several minutes or longer.</p>
<p>The local server will only have the power to move local user and room aliases to
the new room. Users on other servers will be unaffected.</p>
+<p>To use it, you will need to authenticate by providing an <code>access_token</code> for a
+server admin: see <a href="admin_api/../usage/administration/admin_api">Admin API</a>.</p>
+<h2 id="version-1-old-version"><a class="header" href="#version-1-old-version">Version 1 (old version)</a></h2>
+<p>This version works synchronously. That means you only get the response once the server has
+finished the action, which may take a long time. If you request the same action
+a second time, and the server has not finished the first one, the second request will block.
+This is fixed in version 2 of this API. The parameters are the same in both APIs.
+This API will become deprecated in the future.</p>
<p>The API is:</p>
<pre><code>DELETE /_synapse/admin/v1/rooms/<room_id>
</code></pre>
@@ -10287,8 +10406,6 @@ the new room. Users on other servers will be unaffected.</p>
"purge": true
}
</code></pre>
-<p>To use it, you will need to authenticate by providing an <code>access_token</code> for a
-server admin: see <a href="admin_api/../usage/administration/admin_api">Admin API</a>.</p>
<p>A response body like the following is returned:</p>
<pre><code class="language-json">{
"kicked_users": [
@@ -10302,6 +10419,31 @@ server admin: see <a href="admin_api/../usage/administration/admin_api">Admin AP
"new_room_id": "!newroomid:example.com"
}
</code></pre>
+<p>The parameters and response values have the same format as
+<a href="admin_api/rooms.html#version-2-new-version">version 2</a> of the API.</p>
+<h2 id="version-2-new-version"><a class="header" href="#version-2-new-version">Version 2 (new version)</a></h2>
+<p><strong>Note</strong>: This API is new, experimental and "subject to change".</p>
+<p>This version works asynchronously, meaning you get the response from server immediately
+while the server works on that task in background. You can then request the status of the action
+to check if it has completed.</p>
+<p>The API is:</p>
+<pre><code>DELETE /_synapse/admin/v2/rooms/<room_id>
+</code></pre>
+<p>with a body of:</p>
+<pre><code class="language-json">{
+ "new_room_user_id": "@someuser:example.com",
+ "room_name": "Content Violation Notification",
+ "message": "Bad Room has been shutdown due to content violations on this server. Please review our Terms of Service.",
+ "block": true,
+ "purge": true
+}
+</code></pre>
+<p>The API starts the shut down and purge running, and returns immediately with a JSON body with
+a purge id:</p>
+<pre><code class="language-json">{
+ "delete_id": "<opaque id>"
+}
+</code></pre>
<p><strong>Parameters</strong></p>
<p>The following parameters should be set in the URL:</p>
<ul>
@@ -10319,8 +10461,10 @@ invited to. Defaults to <code>Content Violation Notification</code></li>
<li><code>message</code> - Optional. A string containing the first message that will be sent as
<code>new_room_user_id</code> in the new room. Ideally this will clearly convey why the
original room was shut down. Defaults to <code>Sharing illegal content on this server is not permitted and rooms in violation will be blocked.</code></li>
-<li><code>block</code> - Optional. If set to <code>true</code>, this room will be added to a blocking list, preventing
-future attempts to join the room. Defaults to <code>false</code>.</li>
+<li><code>block</code> - Optional. If set to <code>true</code>, this room will be added to a blocking list,
+preventing future attempts to join the room. Rooms can be blocked
+even if they're not yet known to the homeserver (only with
+<a href="admin_api/rooms.html#version-1-old-version">Version 1</a> of the API). Defaults to <code>false</code>.</li>
<li><code>purge</code> - Optional. If set to <code>true</code>, it will remove all traces of the room from your database.
Defaults to <code>true</code>.</li>
<li><code>force_purge</code> - Optional, and ignored unless <code>purge</code> is <code>true</code>. If set to <code>true</code>, it
@@ -10329,14 +10473,111 @@ use this unless a regular <code>purge</code> operation fails, as it could leave
clients in a confused state.</li>
</ul>
<p>The JSON body must not be empty. The body must be at least <code>{}</code>.</p>
-<p><strong>Response</strong></p>
+<h2 id="status-of-deleting-rooms"><a class="header" href="#status-of-deleting-rooms">Status of deleting rooms</a></h2>
+<p><strong>Note</strong>: This API is new, experimental and "subject to change".</p>
+<p>It is possible to query the status of the background task for deleting rooms.
+The status can be queried up to 24 hours after completion of the task,
+or until Synapse is restarted (whichever happens first).</p>
+<h3 id="query-by-room_id"><a class="header" href="#query-by-room_id">Query by <code>room_id</code></a></h3>
+<p>With this API you can get the status of all active deletion tasks, and all those completed in the last 24h,
+for the given <code>room_id</code>.</p>
+<p>The API is:</p>
+<pre><code>GET /_synapse/admin/v2/rooms/<room_id>/delete_status
+</code></pre>
+<p>A response body like the following is returned:</p>
+<pre><code class="language-json">{
+ "results": [
+ {
+ "delete_id": "delete_id1",
+ "status": "failed",
+ "error": "error message",
+ "shutdown_room": {
+ "kicked_users": [],
+ "failed_to_kick_users": [],
+ "local_aliases": [],
+ "new_room_id": null
+ }
+ }, {
+ "delete_id": "delete_id2",
+ "status": "purging",
+ "shutdown_room": {
+ "kicked_users": [
+ "@foobar:example.com"
+ ],
+ "failed_to_kick_users": [],
+ "local_aliases": [
+ "#badroom:example.com",
+ "#evilsaloon:example.com"
+ ],
+ "new_room_id": "!newroomid:example.com"
+ }
+ }
+ ]
+}
+</code></pre>
+<p><strong>Parameters</strong></p>
+<p>The following parameters should be set in the URL:</p>
+<ul>
+<li><code>room_id</code> - The ID of the room.</li>
+</ul>
+<h3 id="query-by-delete_id"><a class="header" href="#query-by-delete_id">Query by <code>delete_id</code></a></h3>
+<p>With this API you can get the status of one specific task by <code>delete_id</code>.</p>
+<p>The API is:</p>
+<pre><code>GET /_synapse/admin/v2/rooms/delete_status/<delete_id>
+</code></pre>
+<p>A response body like the following is returned:</p>
+<pre><code class="language-json">{
+ "status": "purging",
+ "shutdown_room": {
+ "kicked_users": [
+ "@foobar:example.com"
+ ],
+ "failed_to_kick_users": [],
+ "local_aliases": [
+ "#badroom:example.com",
+ "#evilsaloon:example.com"
+ ],
+ "new_room_id": "!newroomid:example.com"
+ }
+}
+</code></pre>
+<p><strong>Parameters</strong></p>
+<p>The following parameters should be set in the URL:</p>
+<ul>
+<li><code>delete_id</code> - The ID for this delete.</li>
+</ul>
+<h3 id="response"><a class="header" href="#response">Response</a></h3>
<p>The following fields are returned in the JSON response body:</p>
<ul>
+<li><code>results</code> - An array of objects, each containing information about one task.
+This field is omitted from the result when you query by <code>delete_id</code>.
+Task objects contain the following fields:
+<ul>
+<li><code>delete_id</code> - The ID for this purge if you query by <code>room_id</code>.</li>
+<li><code>status</code> - The status will be one of:
+<ul>
+<li><code>shutting_down</code> - The process is removing users from the room.</li>
+<li><code>purging</code> - The process is purging the room and event data from database.</li>
+<li><code>complete</code> - The process has completed successfully.</li>
+<li><code>failed</code> - The process is aborted, an error has occurred.</li>
+</ul>
+</li>
+<li><code>error</code> - A string that shows an error message if <code>status</code> is <code>failed</code>.
+Otherwise this field is hidden.</li>
+<li><code>shutdown_room</code> - An object containing information about the result of shutting down the room.
+<em>Note:</em> The result is shown after removing the room members.
+The delete process can still be running. Please pay attention to the <code>status</code>.
+<ul>
<li><code>kicked_users</code> - An array of users (<code>user_id</code>) that were kicked.</li>
<li><code>failed_to_kick_users</code> - An array of users (<code>user_id</code>) that that were not kicked.</li>
-<li><code>local_aliases</code> - An array of strings representing the local aliases that were migrated from
-the old room to the new.</li>
-<li><code>new_room_id</code> - A string representing the room ID of the new room.</li>
+<li><code>local_aliases</code> - An array of strings representing the local aliases that were
+migrated from the old room to the new.</li>
+<li><code>new_room_id</code> - A string representing the room ID of the new room, or <code>null</code> if
+no such room was created.</li>
+</ul>
+</li>
+</ul>
+</li>
</ul>
<h2 id="undoing-room-deletions"><a class="header" href="#undoing-room-deletions">Undoing room deletions</a></h2>
<p><em>Note</em>: This guide may be outdated by the time you read it. By nature of room deletions being performed at the database level,
@@ -11463,7 +11704,7 @@ Max length, 512 bytes.</p>
</ul>
<p>See also the
<a href="https://matrix.org/docs/spec/client_server/latest#get-matrix-client-r0-pushers">Client-Server API Spec on pushers</a>.</p>
-<h2 id="shadow-banning-users"><a class="header" href="#shadow-banning-users">Shadow-banning users</a></h2>
+<h2 id="controlling-whether-a-user-is-shadow-banned"><a class="header" href="#controlling-whether-a-user-is-shadow-banned">Controlling whether a user is shadow-banned</a></h2>
<p>Shadow-banning is a useful tool for moderating malicious or egregiously abusive users.
A shadow-banned users receives successful responses to their client-server API requests,
but the events are not propagated into rooms. This can be an effective tool as it
@@ -11473,12 +11714,15 @@ pivoting to another account.</p>
or broken behaviour for the client. A shadow-banned user will not receive any
notification and it is generally more appropriate to ban or kick abusive users.
A shadow-banned user will be unable to contact anyone on the server.</p>
-<p>The API is:</p>
+<p>To shadow-ban a user the API is:</p>
<pre><code>POST /_synapse/admin/v1/users/<user_id>/shadow_ban
</code></pre>
+<p>To un-shadow-ban a user the API is:</p>
+<pre><code>DELETE /_synapse/admin/v1/users/<user_id>/shadow_ban
+</code></pre>
<p>To use it, you will need to authenticate by providing an <code>access_token</code> for a
server admin: <a href="admin_api/../usage/administration/admin_api">Admin API</a></p>
-<p>An empty JSON dict is returned.</p>
+<p>An empty JSON dict is returned in both cases.</p>
<p><strong>Parameters</strong></p>
<p>The following parameters should be set in the URL:</p>
<ul>
@@ -11573,7 +11817,7 @@ for more information.</p>
<p>This endpoint will work even if registration is disabled on the server, unlike
<code>/_matrix/client/r0/register/available</code>.</p>
<p>The API is:</p>
-<pre><code>POST /_synapse/admin/v1/username_availabile?username=$localpart
+<pre><code>GET /_synapse/admin/v1/username_available?username=$localpart
</code></pre>
<p>The request and response format is the same as the <a href="https://matrix.org/docs/spec/client_server/r0.6.0#get-matrix-client-r0-register-available">/_matrix/client/r0/register/available</a> API.</p>
<p>To use it, you will need to authenticate by providing an <code>access_token</code> for a
|
