doc/source: Document authenticate function usage

Signed-off-by: hamistao <[email protected]>

doc/source/authentication.rst

@@ -37,10 +37,23 @@ essentially meaning that the authentication has not yet occurred.
     False
 
 In order to authenticate the client, pass the LXD instance's trust
-password or token to `Client.authenticate`
+password or token to `Client.authenticate`.
+The secret provided will be use as a token if it has the proper format
+and the server accepts tokens, otherwise it will be used as a password.
+To force password authentication, `use_token_auth` can be used.
 
 .. code-block:: python
 
     >>> client.authenticate('a-secret')
     >>> client.trusted
     >>> True
+
+.. code-block:: python
+
+    >>> token = '{"client_name":"foo","fingerprint":"abcd","addresses":["192.0.2.1:8443"],"secret":"I-am-a-secret","expires_at":"0001-01-01T00:00:00Z","type":""}'
+    >>> client.authenticate(base64.b64encode(json.dumps(token).encode("utf-8")), use_token_auth=False) # Forces password authentication and fails
+    >>> client.trusted
+    >>> False
+    >>> client.authenticate(base64.b64encode(json.dumps(token).encode("utf-8"))) # Token used as token
+    >>> client.trusted
+    >>> True