Getting an API token

The Arvados API token is a secret key that enables the Arvados command line tools to authenticate themselves.

Access the Arvados Workbench using this link: https://playground.arvados.org/ (Replace the hostname portion with the hostname of your local Arvados instance if necessary.)

Open a shell on the system where you want to use the Arvados client. This may be your local workstation, or an Arvados virtual machine accessed with Webshell or SSH (instructions for Unix or Windows).

In the Arvados Workbench, click on the dropdown menu icon in the upper right corner of the top navigation menu to access the Account Management menu. Then, in the pop-up menu, click on the menu item Get API token. This will open a dialog box that lists your current token and the instructions for setting up your environment.

Setting environment variables

In the dialog box opened after clicking on the Get API token menu item, there is a sequence of commands you may copy and paste directly into the shell. It will look something as the following.

HISTIGNORE=$HISTIGNORE:'export ARVADOS_API_TOKEN=*'
export ARVADOS_API_TOKEN=2jv9346o396exampledonotuseexampledonotuseexes7j1ld
export ARVADOS_API_HOST=pirca.arvadosapi.com
unset ARVADOS_API_HOST_INSECURE

The export command puts a local shell variable into the environment that will be inherited by child processes such as the arv client.

settings.conf

Arvados tools will also look for the authentication information in ~/.config/arvados/settings.conf. If you have already put the variables into the environment following the instructions above, you can use these commands to create an Arvados configuration file:

$ cat >~/.config/arvados/settings.conf <<EOF
ARVADOS_API_HOST=$ARVADOS_API_HOST
ARVADOS_API_TOKEN=$ARVADOS_API_TOKEN
EOF

Note:

This will overwrite the file ~/.config/arvados/settings.conf.

Arvados tools written in Python (most notably the arv keep commands, arv copy, and arv-mount) search for configuration files following the XDG Base Directory Specification. This is uncommon, but if you have customized the XDG_CONFIG_HOME environment variable, you may need to add $HOME/.config to the XDG_CONFIG_DIRS envirnoment variable to have all the tools find the same configuration.

.bashrc

Alternately, you may add the definitions of ARVADOS_API_HOST and ARVADOS_API_TOKEN to the ~/.bashrc file on the system where you intend to use the Arvados client. If you have already put the variables into the environment following the instructions above, you can use the commands below to append to your ~/.bashrc, which tells Bash to export them as environment variables in newly-started interactive shell sessions:

$ echo "export ARVADOS_API_HOST=$ARVADOS_API_HOST" >> ~/.bashrc
$ echo "export ARVADOS_API_TOKEN=$ARVADOS_API_TOKEN" >> ~/.bashrc

Previous: Getting started at the command line Next: Checking your environment