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 <your-org-name.domain>/manage_tokens. 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:


Clicking 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:

Example of client configuration in code
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.