/
Client Configuration
Document toolboxDocument toolbox

Client Configuration

Owned by Stacey Taylor (Unlicensed)
Last updated: Aug 14, 2025 by Thomas Yu

If you are here, it means you are trying to configure one of Synapse’s API clients to use Synapse programmatically. There are multiple ways one can login to Synapse via the Python, R, command line clients. We recommend users choose the method that fits their workflow best.

Prerequisites

  • Create a Personal Access Token (aka: Synapse Auth Token) obtained from Synapse under your Settings.

    • Note that a token must minimally have the view scope to be used.

    • Include Download and Modify permissions if you are using the clients to follow any subsequent tutorials.

  • Once a personal access token has been created it can be used for any of the options below.

One Time Login

Python

Use the synapseclient.login function

import synapseclient syn = synapseclient.login(authToken="authtoken") #returns Welcome, First Last!

Command Line Client

Use the synapse login command

synapse login -p $MY_SYNAPSE_TOKEN

R

library(synapser) synLogin(authToken="authtoken")

Use .synapseConfig

Synapse configuration parameters for frequently used client-interactions can be set in a configuration file. By default, the file is in the user’s home directory and is called .synapseConfig. For example, you can set:

  • A new cache location

  • Third party credentials to access files stored outside of Synapse (e.g. AWS-S3, etc.)

  • Your Synapse credentials, preferably in the form of an access token

Note the period at the beginning of the file name that makes it a hidden system file on Linux-like operating systems, since it will contain sensitive information. For writing code using the client that is easy to share with others, please do not include your credentials in the code. Instead, please use the ~/.synapseConfig file to manage your credentials.

  • Please read this comprehensive guide to learn how to manage your Synapse Config file with the Python/CLI client.

  • Please read this guide to learn how to manage your Synapse Config file with the R client.

Note: The Python/CLI client currently supports multi-config profiles within the Synapse Config file which is not supported within the R client, but the config file written for the R client will remain to be supported by the Python client.

After you set up your synapse config, the following login commands should work without specifying your credentials within the command.

Python

import synapseclient syn = synapseclient.login() #returns Welcome, First Last!

Command Line Client

Use the synapse login command

synapse login

R

library(synapser) synLogin()

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.

  1. Open your shell configuration file (e.g., ~/.bashrc, ~/.zshrc, or ~/.profile)

  2. Add and save this in the shell configuration file

    export SYNAPSE_AUTH_TOKEN='<my_personal_access_token>'

    1. If you are using R, alternatively, you may save this environmental variable within the .Renviron file of your Rstudio project. More information here.

  3. You will be able to log in like the commands above in the “Use ~/.synapseConfig" section. Here are some alternative ways you can log in using the environmental variable for the Python and command line client.