% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/taxize-authentication.R
\name{taxize-authentication}
\alias{taxize-authentication}
\alias{authentication}
\title{taxize authentication}
\description{
Help on authentication
}
\section{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. \pkg{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.
}

\section{What are API keys?}{

For those APIs that require authentication, the way that's typically done
is through API keys: alphanumeric strings of variable lengths that are
supplied with a request to an API.

\pkg{taxize} won't get these keys for you; rather, you have to
go get a key for each service, but we do provide information on how
to get those keys. See \code{\link[=key_helpers]{key_helpers()}} for help on how to
obtain keys for this package.
}

\section{Using API keys}{

You can store API keys as R options in your \code{.Rprofile} file, or
as environment variables in either your \code{.Renviron} file or
\code{.bash_profile} file, o\code{.zshrc} file (if you use oh-my-zsh) or
similar. See \link{Startup} for help on R options and environment
variables.

Save your API keys with the following names:
\itemize{
\item Tropicos: R option or env var as 'TROPICOS_KEY'
\item IUCN: R option or env var as 'IUCN_REDLIST_KEY'
\item ENTREZ: R option or env var as 'ENTREZ_KEY'
}

If you save in .Renviron it looks like: \code{ENTREZ_KEY=somekey}

If you save in a .bash_profile, .zshrc, or similar file it looks like:
\verb{export ENTREZ_KEY=somekey}

If you save in a .Rprofile it looks like: \code{options(ENTREZ_KEY = "somekey")}

Remember to restart your R session (and to start a new shell window/tab
if you're using the shell) to take advantage of the new R options
or environment variables.

We strongly recommend using environment variables
(\url{https://en.wikipedia.org/wiki/Environment_variable}) over R options
because environment variables are widely used across programming
languages, operating systems, and computing environments; whereas
R options are specific to R.

Note that NCBI Entrez doesn't require that you use an API key,
but you do get a higher rate limit with a key (more requests per
time period), from 3 to 10 requests per second, so do get one.
}

\seealso{
\code{\link[=key_helpers]{key_helpers()}}
}
