diff --git a/etc/proxy-server.conf-sample b/etc/proxy-server.conf-sample
index 42fcdfde05..4a1b643b85 100644
--- a/etc/proxy-server.conf-sample
+++ b/etc/proxy-server.conf-sample
@@ -589,7 +589,8 @@ reseller_prefix = AUTH_
 # useful if there are multiple auth systems in the proxy pipeline.
 delay_auth_decision = False
 
-# Keystone server details
+# Keystone server details. Note that this differs from how swift3 was
+# configured: in particular, the Keystone API version must be included.
 auth_uri = http://keystonehost:35357/v3
 
 # Connect/read timeout to use when communicating with Keystone
diff --git a/swift/common/middleware/s3api/s3token.py b/swift/common/middleware/s3api/s3token.py
index db4aa77314..dd4ecfe526 100644
--- a/swift/common/middleware/s3api/s3token.py
+++ b/swift/common/middleware/s3api/s3token.py
@@ -33,6 +33,25 @@ This middleware:
 * Optionally can retrieve and cache secret from keystone
   to validate signature locally
 
+.. note::
+   If upgrading from swift3, the ``auth_version`` config option has been
+   removed, and the ``auth_uri`` option now includes the Keystone API
+   version. If you previously had a configuration like
+
+   .. code-block:: ini
+
+      [filter:s3token]
+      use = egg:swift3#s3token
+      auth_uri = https://keystonehost:35357
+      auth_version = 3
+
+   you should now use
+
+   .. code-block:: ini
+
+      [filter:s3token]
+      use = egg:swift#s3token
+      auth_uri = https://keystonehost:35357/v3
 """
 
 import base64