docs: add a note arguing you should generate tokens

Signed-off-by: Olivier Léobal <[email protected]>

docs/source/documentation/api_tokens_generation.rst

@@ -3,7 +3,24 @@ How-to use new API tokens for login
 
 This short guide explains how to manage API tokens in the web application, and use them in the Substra SDK.
 
-.. note::
+.. admonition:: Why generate API tokens?
+
+   The Substra SDK provides a way to log in using username and password (see `substra.Client <references/sdk.html#client>`_).
+
+   It is safe, but should be used with caution, as it:
+
+   * doesn't allow for a precise lifetime or separating concerns by creating one token per purpose
+
+   * may surprise or limite you through its underlying automated session management
+
+   * can encourage using cleartext passwords, which can end up shared in version control.
+
+   For these reasons, it is possible for Substra node administrators to disable "implicit login" and force users to generate tokens in the web app.
+
+   Whatever the situation, you should use a mechanism to ensure credentials are kept out of view, for instance by reading secret files or environment variables at runtime.
+
+
+.. warning::
    API tokens are node-specific: if your script connects to multiple nodes, generate a token for each of them.
 
 Generating new API tokens