---
layout: default
navsection: userguide
-navmenu: Reference
title: "Getting an API token"
-
...
+{% comment %}
+Copyright (C) The Arvados Authors. All rights reserved.
+
+SPDX-License-Identifier: CC-BY-SA-3.0
+{% endcomment %}
-h1. Reference: Getting an API token
+The Arvados API token is a secret key that enables the Arvados command line tools to authenticate themselves.
-The Arvados API token is a secret key that enables the @arv@ command line
-client to access Arvados with the proper permissions.
+Access the Arvados Workbench using this link: "{{site.arvados_workbench_host}}/":{{site.arvados_workbench_host}}/ (Replace the hostname portion with the hostname of your local Arvados instance if necessary.)
-Access the Arvados workbench using this link:
+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":{{site.baseurl}}/user/getting_started/vm-login-with-webshell.html or SSH (instructions for "Unix":{{site.baseurl}}/user/getting_started/ssh-access-unix.html#login or "Windows":{{site.baseurl}}/user/getting_started/ssh-access-windows.html#login).
-"https://workbench.{{ site.arvados_api_host }}/":https://workbench.{{ site.arvados_api_host }}/
+In the Arvados Workbench, click on the dropdown menu icon <span class="fa fa-lg fa-user"></span> 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.
-(Replace @{{ site.arvados_api_host }}@ with the hostname of your local Arvados instance if necessary.)
+h2. Setting environment variables
-Use the menu to navigate to _Access %(rarr)→% API Tokens._ There should be one or more rows. The column *api_token* contains the actual token string that you will use. Copy the value of *api_token* for the first row onto the clipboard.
+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.
-Next, open a shell on the system on which you intend to use the Arvados client (refer to "Accessing Arvados over ssh":{{site.basedoc}}/user/getting_started/ssh-access.html ) and enter the following (replace the value of @ARVADOS_API_TOKEN@ with the value you copied from the Workbench):
+bc. HISTIGNORE=$HISTIGNORE:'export ARVADOS_API_TOKEN=*'
+export ARVADOS_API_TOKEN=2jv9346o396exampledonotuseexampledonotuseexes7j1ld
+export ARVADOS_API_HOST={{ site.arvados_api_host }}
+unset ARVADOS_API_HOST_INSECURE
-bc. $ export ARVADOS_API_HOST={{ site.arvados_api_host }}
-$ export ARVADOS_API_TOKEN=2jv9kd1o39t0pcfu7aueem7a1zjxhak73w90tzq3gx0es7j1ld
+* The @export@ command puts a local shell variable into the environment that will be inherited by child processes such as the @arv@ client.
-* @ARVADOS_API_HOST@ tells @arv@ which host to connect to
-* @ARVADOS_API_TOKEN@ is the secret key used by the Arvados API server to authenticate access.
+h2. settings.conf
-For your convenience, the "API Tokens" Workbench page provides a section at the top of the page that you may copy and paste directly into the shell. It will look something like this:
+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:
-bc. ### Pasting the following lines at a shell prompt will allow Arvados SDKs
-### to authenticate to your account, youraddress@example.com
-read ARVADOS_API_TOKEN <<EOF
-2jv9kd1o39t0pcfu7aueem7a1zjxhak73w90tzq3gx0es7j1ld
-EOF
-export ARVADOS_API_TOKEN ARVADOS_API_HOST=qr1hi.arvadosapi.com
+<notextile>
+<pre><code>$ <span class="userinput">echo "ARVADOS_API_HOST=$ARVADOS_API_HOST" > ~/.config/arvados/settings.conf</span>
+$ <span class="userinput">echo "ARVADOS_API_TOKEN=$ARVADOS_API_TOKEN" >> ~/.config/arvados/settings.conf</span>
+</code></pre>
+</notextile>
-* The @read@ command takes the contents of stdin and puts it into the shell variable named on the command line.
-* The @<<EOF@ notation means read each line on stdin and pipe it to the command, terminating on reading the line @EOF@.
-* The @export@ command puts a local shell variable into the environment that will be inherited by child processes (e.g. the @arv@ client).
+* The output-redirection operator @>@ in the first command will cause the target file @~/.config/arvados/settings.conf@ to be created anew, wiping out the content of any existing file at that path.
+* The @>>@ operator in the second command appends to the target file.
-For your convenience you may add the declarations of @ARVADOS_API_HOST@ and @ARVADOS_API_TOKEN@ to the @~/.bashrc@ file on the system on which you intend to use the Arvados client. If you have already put the variables into the environment with instructions above, you can use these commands to append the environment variables to your @~/.bashrc@:
+h2. .bashrc
-bc. $ echo "export ARVADOS_API_HOST=$ARVADOS_API_HOST" >> ~/.bashrc
-$ echo "export ARVADOS_API_TOKEN=$ARVADOS_API_TOKEN" >> ~/.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:
+<notextile>
+<pre><code>$ <span class="userinput">echo "export ARVADOS_API_HOST=$ARVADOS_API_HOST" >> ~/.bashrc</span>
+$ <span class="userinput">echo "export ARVADOS_API_TOKEN=$ARVADOS_API_TOKEN" >> ~/.bashrc</span>
+</code></pre>
+</notextile>
projects / arvados.git / blobdiff