Manage Synapse Credentials

There are multiple ways one can login to Synapse. We recommend users to choose the method that fits their workflow.

One Time Login

Use username and password to login as follows:

import synapseclient
syn = synapseclient.login("username", "password")

Alternately you can login using a personal access token obtained from synapse.org under your Settings. Note that a token must minimally have the view scope to be used with the Synapse Python Client.

syn = synapseclient.login(authToken="authtoken")

Use Environment Variable

Setting the SYNAPSE_AUTH_TOKEN environment variable will allow you to login to Synapse with a personal access token.

The environment variable will take priority over credentials in the user’s .synapseConfig file or any credentials saved in a prior login using syn.login(rememberMe=True).

In your shell, you can pass an environment variable to Python inline by defining it before the command:

SYNAPSE_AUTH_TOKEN='<my_personal_access_token>' python3

Alternatively you may export it first, then start: Python

export SYNAPSE_AUTH_TOKEN='<my_personal_access_token>'
python3

Once you are inside Python, you may simply login without passing any arguments:

import synapseclient
syn = synapseclient.login()

To use the environment variable with the command line client, simply substitute python for the synapse command

SYNAPSE_AUTH_TOKEN='<my_personal_access_token>' synapse get syn123
SYNAPSE_AUTH_TOKEN='<my_personal_access_token>' synapse store --parentid syn123 ~/foobar.txt

Or alternatively, for multiple commands:

export SYNAPSE_AUTH_TOKEN='<my_personal_access_token>'
synapse get syn123
synapse store --parentid syn123 ~/foobar.txt

Use .synapseConfig

For writing code using the Synapse Python client that is easy to share with others, please do not include your credentials in the code. Instead, please use .synapseConfig file to manage your credentials.

When installing the Synapse Python client, the .synapseConfig is added to your home directory. Open the .synapseConfig file and find the following section:

#[authentication]
#username = <username>
#password = <password>
#authtoken = <authtoken>

To enable this section, uncomment it. You will only need to specify either username and password as a pair, or authtoken. For security purposes, we recommend that you use authtoken instead of username and password. A personal access token generated from your synapse.org Settings can be used as your .synapseConfig authtoken.

[authentication]
authtoken = <authtoken>

Now, you can login without specifying any arguments:

import synapseclient
syn = synapseclient.login()

For legacy compatibility, the .synapseConfig [authentication] section also supports apikey, which can be used instead of username + password pair, or authtoken, however apikey support in the .synapseConfig is considered deprecated in favor of personal access tokens (authtoken) which can be scoped to certain functions and are revocable. If needed, your legacy apikey can also be obtained from your synapse.org Settings.

Letting the Operating System Manage Your Synapse Credentials

For users who would like to save their credentials and let other OS configured applications (like keychain in Mac) manage credentials for them, when logging in for the first time, use:

import synapseclient
syn = synapseclient.login("username", "password", rememberMe=True)

The application (keychain in Mac) will then prompt you to allow Python to access these credentials. Please choose “Yes” or “OK”.

The second time you login, you will not have to enter any arguments to login():

import synapseclient
syn = synapseclient.login()