Update save_bearer_token docs to mention how the token is passed in as a reference (#556)

1 files changed, 8 insertions, 1 deletions

diff --git a/oauthlib/oauth2/rfc6749/request_validator.py b/oauthlib/oauth2/rfc6749/request_validator.py
index 92edba6..bf1515d 100644
--- a/oauthlib/oauth2/rfc6749/request_validator.py
+++ b/oauthlib/oauth2/rfc6749/request_validator.py
@@ -332,7 +332,14 @@ class RequestValidator(object):
             }
 
         Note that while "scope" is a string-separated list of authorized scopes,
-        the original list is still available in request.scopes
+        the original list is still available in request.scopes.
+
+        The token dict is passed as a reference so any changes made to the dictionary
+        will go back to the user.  If additional information must return to the client
+        user, and it is only possible to get this information after writing the token
+        to storage, it should be added to the token dictionary.  If the token
+        dictionary must be modified but the changes should not go back to the user,
+        a copy of the dictionary must be made before making the changes.
 
         Also note that if an Authorization Code grant request included a valid claims
         parameter (for OpenID Connect) then the request.claims property will contain