diff --git a/doc/rapi.rst b/doc/rapi.rst
index e69fa19bf94e5fc1983c9a4f6cc2c0494608b3b8..f70f8ca1acb1ba4ae8ee2b15eea5da1fa0928fde 100644
--- a/doc/rapi.rst
+++ b/doc/rapi.rst
@@ -16,6 +16,7 @@ it runs on TCP port 5080, but this can be changed either in
 which is used by default, can also be disabled by passing command line
 parameters.
 
+.. _rapi-users:
 
 Users and passwords
 -------------------
@@ -64,10 +65,11 @@ Example::
   jessica {HA1}7046452df2cbb530877058712cf17bd4 write
 
   # Monitoring can query for values
-  monitoring {HA1}ec018ffe72b8e75bb4d508ed5b6d079c query
+  monitoring {HA1}ec018ffe72b8e75bb4d508ed5b6d079c read
 
-  # A user who can query and write
-  superuser {HA1}ec018ffe72b8e75bb4d508ed5b6d079c query,write
+  # A user who can read and write (the former is implied by granting
+  # write access)
+  superuser {HA1}ec018ffe72b8e75bb4d508ed5b6d079c read,write
 
 
 .. [#pwhash] Using the MD5 hash of username, realm and password is
diff --git a/doc/security.rst b/doc/security.rst
index a24d7ffe55b9b296c3193b63fcaec5d80245bdc0..70d1d9556ac584c1e7fb46e49d4dd7c3b918ac98 100644
--- a/doc/security.rst
+++ b/doc/security.rst
@@ -98,7 +98,9 @@ Remote API
 ----------
 
 Starting with Ganeti 2.0, Remote API traffic is encrypted using SSL/TLS
-by default. It supports Basic authentication as per :rfc:`2617`.
+by default. It supports Basic authentication as per :rfc:`2617`. Users
+can be granted different capabilities. Details can be found in the
+:ref:`RAPI documentation <rapi-users>`.
 
 Paths for certificate, private key and CA files required for SSL/TLS
 will be set at source configure time. Symlinks or command line