From 659c71d81840913deec8771f67203fd10c15dd6c Mon Sep 17 00:00:00 2001
From: DMRobertson <DMRobertson@users.noreply.github.com>
Date: Wed, 13 Jul 2022 18:34:07 +0000
Subject: deploy: 2341032cf2d031e58710d82c9ee1d2360f9b82f9

---
 develop/usage/administration/admin_api/index.html | 13 +++++++++++++
 1 file changed, 13 insertions(+)

(limited to 'develop/usage/administration/admin_api/index.html')

diff --git a/develop/usage/administration/admin_api/index.html b/develop/usage/administration/admin_api/index.html
index 719e91c0c9..d4738efe75 100644
--- a/develop/usage/administration/admin_api/index.html
+++ b/develop/usage/administration/admin_api/index.html
@@ -158,10 +158,23 @@ command. This is a script that is distributed as part of synapse. It is possibly
 already on your <code>$PATH</code> depending on how Synapse was installed.</p>
 <p>Finding your user's <code>access_token</code> is client-dependent, but will usually be shown in the client's settings.</p>
 <h2 id="making-an-admin-api-request"><a class="header" href="#making-an-admin-api-request">Making an Admin API request</a></h2>
+<p>For security reasons, we <a href="reverse_proxy.html#synapse-administration-endpoints">recommend</a>
+that the Admin API (<code>/_synapse/admin/...</code>) should be hidden from public view using a
+reverse proxy. This means you should typically query the Admin API from a terminal on
+the machine which runs Synapse.</p>
 <p>Once you have your <code>access_token</code>, you will need to authenticate each request to an Admin API endpoint by
 providing the token as either a query parameter or a request header. To add it as a request header in cURL:</p>
 <pre><code class="language-sh">curl --header &quot;Authorization: Bearer &lt;access_token&gt;&quot; &lt;the_rest_of_your_API_request&gt;
 </code></pre>
+<p>For example, suppose we want to
+<a href="user_admin_api.html#query-user-account">query the account</a> of the user
+<code>@foo:bar.com</code>. We need an admin access token (e.g.
+<code>syt_AjfVef2_L33JNpafeif_0feKJfeaf0CQpoZk</code>), and we need to know which port
+Synapse's <a href="config_documentation.html#listeners"><code>client</code> listener</a> is listening
+on (e.g. <code>8008</code>). Then we can use the following command to request the account
+information from the Admin API.</p>
+<pre><code class="language-sh">curl --header &quot;Authorization: Bearer syt_AjfVef2_L33JNpafeif_0feKJfeaf0CQpoZk&quot; -X GET http://127.0.0.1:8008/_synapse/admin/v2/users/@foo:bar.com
+</code></pre>
 <p>For more details on access tokens in Matrix, please refer to the complete
 <a href="https://matrix.org/docs/spec/client_server/r0.6.1#using-access-tokens">matrix spec documentation</a>.</p>
 
-- 
cgit 1.4.1