doc/user/reference/api-tokens.html.textile.liquid

   1 ---
   2 layout: default
   3 navsection: userguide
   4 title: "Getting an API token"
   5 ...
   6
   7 The Arvados API token is a secret key that enables the @arv@ command line client to access Arvados with the proper permissions.
   8
   9 Access the Arvados Workbench using this link: "https://{{ site.arvados_workbench_host }}/":https://{{ site.arvados_workbench_host }}/  (Replace @{{ site.arvados_api_host }}@ with the hostname of your local Arvados instance if necessary.)
  10
  11 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 SSH ("Unix":{{site.baseurl}}/user/getting_started/ssh-access-unix.html#login or "Windows":{{site.baseurl}}/user/getting_started/ssh-access-windows.html#login).
  12
  13 Click on the user icon <span class="glyphicon glyphicon-user"></span> in the upper right corner to access the user settings menu.  Click on the menu item *Manage API tokens* to go to the "Api client authorizations" page.
  14
  15 h2. The easy way
  16
  17 For your convenience, the "Api client authorizations" page on Workbench provides a *Help* tab that includes a command you may copy and paste directly into the shell.  It will look something like this:
  18
  19 bc. ### Pasting the following lines at a shell prompt will allow Arvados SDKs
  20 ### to authenticate to your account, you@example.com
  21 read ARVADOS_API_TOKEN <<EOF
  22 2jv9346o396exampledonotuseexampledonotuseexes7j1ld
  23 EOF
  24 export ARVADOS_API_TOKEN ARVADOS_API_HOST={{ site.arvados_api_host }}
  25
  26 * The @read@ command reads text input until @EOF@ (designated by @<<EOF@) and stores it in the @ARVADOS_API_TOKEN@ environment variable.
  27 * The @export@ command puts a local shell variable into the environment that will be inherited by child processes such as the @arv@ client.
  28
  29 h2. Setting the environment manually
  30
  31 Alternately, look for 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.
  32
  33 <notextile>
  34 <pre><code>$ <span class="userinput">export ARVADOS_API_HOST={{ site.arvados_api_host }}</span>
  35 $ <span class="userinput">export ARVADOS_API_TOKEN=2jv9346o3966345u7ueuim7a1zaaoueo3w90tzq3gx0es7j1ld</span>
  36 </code></pre>
  37 </notextile>
  38
  39 * @ARVADOS_API_HOST@ tells @arv@ which host to connect to.
  40 * @ARVADOS_API_TOKEN@ is the secret key used by the Arvados API server to authenticate access.  Its value is the text you copied from the *api_token* column on the Workbench.
  41
  42 If you are connecting to a development instance with a unverified/self-signed SSL certificate, set this variable to skip SSL validation:
  43
  44 <notextile>
  45 <pre><code>$ <span class="userinput">export ARVADOS_API_HOST_INSECURE=1
  46 </code></pre>
  47 </notextile>
  48
  49 h2. settings.conf
  50
  51 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:
  52
  53 <notextile>
  54 <pre><code>$ <span class="userinput">echo "ARVADOS_API_HOST=$ARVADOS_API_HOST" > ~/.config/arvados/settings.conf</span>
  55 $ <span class="userinput">echo "ARVADOS_API_TOKEN=$ARVADOS_API_TOKEN" >> ~/.config/arvados/settings.conf</span>
  56 </code></pre>
  57 </notextile>
  58
  59 h2. .bashrc
  60
  61 Alternately, 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 following the instructions above, you can use these commands to append the environment variables to your @~/.bashrc@:
  62
  63 <notextile>
  64 <pre><code>$ <span class="userinput">echo "export ARVADOS_API_HOST=$ARVADOS_API_HOST" >> ~/.bashrc</span>
  65 $ <span class="userinput">echo "export ARVADOS_API_TOKEN=$ARVADOS_API_TOKEN" >> ~/.bashrc</span>
  66 </code></pre>
  67 </notextile>