03-authentication.Rmd

# Authentication {#authentication}

First, what is an API? An API is an Application Programming Interface.
The term "API" can be used for lots of scenarios, but in this case we're
talking about web APIs, or APIs (interfaces) to web resources. `taxize`
interacts with remote databases on the web via their APIs. You don't need
to worry about the details of how that all works; just know that some of them
require authentication and some do not.

Some data sources in `taxize` require authentication. Here's a breakdown of which
ones require authentication, and how to do authentication by data source:

* **Tropicos**: Request a Tropicos API key from <http://services.tropicos.org/help?requestkey>
* **NCBI Entrez**: From NCBI's docs: "E-utils users are allowed 3
requests/second without an API key. Create an API key (in your account at
<https://www.ncbi.nlm.nih.gov/account/>) to increase your e-utils limit to 10
requests/second. Contact our help department (eutilities@ncbi.nlm.nih.gov)
if you need higher throughput. Only one API Key per user. Replacing or
deleting will inactivate the current key. Refer to documentation
(<https://www.ncbi.nlm.nih.gov/books/NBK25497/>) for more."
* **IUCN**: Request an API key at <http://apiv3.iucnredlist.org/api/v3/token>.
Note that some users have reported waiting many weeks for a key.

Save your API keys as the following names either as R options or
environment variables:

* Tropicos: 'TROPICOS_KEY'
* IUCN: 'IUCN_REDLIST_KEY'
* ENTREZ: 'ENTREZ_KEY'

We'll read in your keys if we can find them in either R options or environment variables.
See `?Startup` in R for details on how to store R options or environment variables.

We recommend using environment variables (<https://en.wikipedia.org/wiki/Environment_variable>)
over R options in general. An added bonus of using environment variables is that
they are widley used across programming languages and computing environments.

When in R, taxize helper functions are provided to help you obtain and setup API keys
for each data source that requires them:

* `taxize::use_tropicos()`
* `taxize::use_entrez()`
* `taxize::use_iucn()`