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.
Why generate API tokens?
The Substra SDK provides a way to log in using username and password (see substra.Client).
It is safe, but should be used with caution:
It doesn’t allow for a precise lifetime or separating concerns by creating one token per purpose.
It may surprise or limit you through its underlying automated session management.
It can encourage using cleartext passwords, which can end up shared in version control.
For these reasons, it is possible for Substra node administrators (via chart options) 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 (see How-to configure Substra clients).
API tokens are node-specific: if your script connects to multiple nodes, generate a token for each of them.
Generating new API tokens¶
To do so you need to go to the API tokens management page on the web application following this link
You will see a list of your current tokens as well as an option to generate new ones.
You can also navigate to the page using the user menu:
Generate new opens a menu allowing you to pick a name and an expiration date for
your new token.
Afterward your token will be shown only once. Do copy it somewhere safe before proceeding with your work.
Using API tokens¶
Pass tokens to the substra.Client constructor:
client_1 = substra.Client(
See How-to configure Substra clients for other options.
Deleting API tokens¶
Tokens can be deleted using the web application. Be careful, token deletion is irreversible.
If you have scripts using a deleted token, they will no longer execute.