diff --git a/README.rst b/README.rst
index 3a09e3e961..6267cf24a0 100644
--- a/README.rst
+++ b/README.rst
@@ -328,7 +328,10 @@ For example:
 OAuth
 -----
 
-*gallery-dl* supports user authentication via OAuth_ for
+*gallery-dl* supports user authentication via OAuth_ for some extractors.
+This is necessary for
+``pixiv``
+and optional for
 ``deviantart``,
 ``flickr``,
 ``reddit``,
@@ -336,12 +339,12 @@ OAuth
 ``tumblr``,
 and ``mastodon`` instances.
 
-This is mostly optional, but grants *gallery-dl* the ability
-to issue requests on your account's behalf and enables it to access resources
-which would otherwise be unavailable to a public user.
+Linking your account to *gallery-dl* grants it the ability to issue requests
+on your account's behalf and enables it to access resources which would
+otherwise be unavailable to a public user.
 
-To link your account to *gallery-dl*, start by invoking it with
-``oauth:<sitename>`` as an argument. For example:
+To do so, start by invoking it with ``oauth:<sitename>`` as an argument.
+For example:
 
 .. code:: bash
 
diff --git a/docs/configuration.rst b/docs/configuration.rst
index 39acf9f860..84a7372ef3 100644
--- a/docs/configuration.rst
+++ b/docs/configuration.rst
@@ -1845,8 +1845,24 @@ Description
     List of acceptable content ratings for returned chapters.
 
 
-extractor.mastodon.reblogs
---------------------------
+extractor.[mastodon].access-token
+---------------------------------
+Type
+    ``string``
+Default
+    ``null``
+Description
+    The ``access-token`` value you get from `linking your account to
+    gallery-dl <OAuth_>`__.
+
+    Note: gallery-dl comes with built-in tokens for ``mastodon.social``,
+    ``pawoo`` and ``baraag``. For other instances, you need to obtain an
+    ``access-token`` in order to use usernames in place of numerical
+    user IDs. 
+
+
+extractor.[mastodon].reblogs
+----------------------------
 Type
     ``bool``
 Default
@@ -1855,8 +1871,8 @@ Description
     Fetch media from reblogged posts.
 
 
-extractor.mastodon.replies
---------------------------
+extractor.[mastodon].replies
+----------------------------
 Type
     ``bool``
 Default
@@ -1865,8 +1881,8 @@ Description
     Fetch media from replies to other posts.
 
 
-extractor.mastodon.text-posts
------------------------------
+extractor.[mastodon].text-posts
+-------------------------------
 Type
     ``bool``
 Default