doc/user/api-tokens.textile

   1 ---
   2 layout: default
   3 navsection: userguide
   4 title: Getting an API token
   5 navorder: 1
   6 ---
   7
   8 h1. Getting an API token
   9
  10 The Arvados API token is a secret key that enables the @arv@ command line
  11 client to access Arvados with the proper permissions.
  12
  13 Access the Arvados workbench using this link:
  14
  15 "https://workbench.{{ site.arvados_api_host }}/":https://workbench.{{ site.arvados_api_host }}/
  16
  17 (Replace @{{ site.arvados_api_host }}@ with the hostname of your local Arvados instance if necessary.)
  18
  19 Use the menu to navigate to _Access %(rarr)&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.
  20
  21 Next, open a shell on the system on which you intend to use the Arvados client (refer to "Accessing Arvados over ssh":ssh-access.html ) and enter the following (replace the value of @ARVADOS_API_TOKEN@ with the value you copied from the Workbench):
  22
  23 <pre>
  24  $ export ARVADOS_API_HOST={{ site.arvados_api_host }}
  25  $ export ARVADOS_API_TOKEN=2jv9kd1o39t0pcfu7aueem7a1zjxhak73w90tzq3gx0es7j1ld
  26 </pre>
  27
  28 * @ARVADOS_API_HOST@ tells @arv@ which host to connect to
  29 * @ARVADOS_API_TOKEN@ is the secret key used by the Arvados API server to authenticate access.
  30
  31 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:
  32
  33 <pre>
  34 ### Pasting the following lines at a shell prompt will allow Arvados SDKs
  35 ### to authenticate to your account, youraddress@example.com
  36
  37 read ARVADOS_API_TOKEN <<EOF
  38 2jv9kd1o39t0pcfu7aueem7a1zjxhak73w90tzq3gx0es7j1ld
  39 EOF
  40 export ARVADOS_API_TOKEN ARVADOS_API_HOST=qr1hi.arvadosapi.com
  41 </pre>
  42
  43 * The @read@ command takes the contents of stdin and puts it into the shell variable named on the command line.
  44 * The @<<EOF@ notation means read each line on stdin and pipe it to the command, terminating on reading the line @EOF@.
  45 * The @export@ command puts a local shell variable into the environment that will be inherited by child processes (e.g. the @arv@ client).
  46
  47 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@:
  48
  49 <pre>
  50  $ echo "export ARVADOS_API_HOST=$ARVADOS_API_HOST" >> ~/.bashrc
  51  $ echo "export ARVADOS_API_TOKEN=$ARVADOS_API_TOKEN" >> ~/.bashrc
  52 </pre>
  53
  54 You are now ready to go through "Tutorial 1":tutorial-job1.html .