diff --git a/keystoneclient/auth/identity/base.py b/keystoneclient/auth/identity/base.py
index 752ba37e1..09af1fae8 100644
--- a/keystoneclient/auth/identity/base.py
+++ b/keystoneclient/auth/identity/base.py
@@ -98,6 +98,18 @@ class BaseIdentityPlugin(base.BaseAuthPlugin):
         return self.auth_ref
 
     def invalidate(self):
+        """Invalidate the current authentication data.
+
+        This should result in fetching a new token on next call.
+
+        A plugin may be invalidated if an Unauthorized HTTP response is
+        returned to indicate that the token may have been revoked or is
+        otherwise now invalid.
+
+        :returns bool: True if there was something that the plugin did to
+                       invalidate. This means that it makes sense to try again.
+                       If nothing happens returns False to indicate give up.
+        """
         self.auth_ref = None
         return True