% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/login.R
\name{dse_access_token}
\alias{dse_access_token}
\alias{dse_public_access_token}
\alias{dse_get_client_id}
\alias{dse_set_client_id}
\alias{dse_set_username}
\alias{dse_set_password}
\alias{dse_get_client_secret}
\alias{dse_get_username}
\alias{dse_get_password}
\alias{dse_set_client_secret}
\alias{dse_has_client_info}
\alias{dse_has_account}
\title{Client Information and Access Token for the Data Space Store API}
\usage{
dse_access_token(
  client_id = dse_get_client_id(),
  client_secret = dse_get_client_secret(),
  ...
)

dse_public_access_token(
  username = dse_get_username(),
  password = dse_get_password()
)

dse_get_client_id(...)

dse_set_client_id(value, ...)

dse_set_username(value, ...)

dse_set_password(value, ...)

dse_get_client_secret(...)

dse_get_username(...)

dse_get_password(...)

dse_set_client_secret(value, ...)

dse_has_client_info(...)

dse_has_account(...)
}
\arguments{
\item{client_id}{ID of the client registered under your account.}

\item{client_secret}{Secret provided for the client registered under your account.}

\item{...}{Ignored}

\item{username}{Your Copernicus Data Space username (usually your e-mail address).}

\item{password}{Your Copernicus Data Space password for your account.}

\item{value}{Assignment value for setting \code{username}, \code{password}, \code{client_id}
or \code{client_secret} as environment variable. Once set, it will persist for
the remainder of the R session.}
}
\value{
In case of \code{dse_get_client_id()} and \code{dse_get_client_secret()}, you can get (or
set) client details as environment variables. This way, they will persist
throughout your R session.

The function \code{dse_has_client_info()} returns a \code{logical} value, indicating
whether client details (id and secret) are available as environmental variable.
Note that if this function returns \code{TRUE}, it doesn't guarantee that the details
are valid (just that they are available).

In case of \code{dse_access_token()} and \code{dse_public_access_token()}
a named \code{list} is returned, containing the
access token (named \code{"token"}) and some additional meta information.
}
\description{
To regulate server traffic, the Data Space Ecosystem uses user accounts to regulate
and ensure fair usage. These functions will get you a token and information about
your usage.
}
\details{
Before you can use most of the Data Space Ecosystem services, you need to create
an account and register as a client. This will let you retrieve an access token,
that can be used for authentication purposes in API requests. It is also used to
manage your usage and rate limiting (see also \code{\link[=dse_usage]{dse_usage()}} and
\code{\link[=dse_user_statistics]{dse_user_statistics()}}).

Note that \href{https://aws.amazon.com/s3/}{Amazon Simple Storage Service (s3)}
has separate authentication requirements. See \code{\link[=dse_s3_get_key]{dse_s3_get_key()}} for details.
\subsection{Creating an Account}{

First step is creating an account. You can create one by visiting the
\href{https://identity.dataspace.copernicus.eu/auth/realms/CDSE/account/#/personal-info}{login page}
and click "register". Fill out the form and follow the instructions.
}

\subsection{Registering Client}{

In order to register a client, visit the
\href{https://shapps.dataspace.copernicus.eu/dashboard/}{Sentinel Dashboard} and
go to "User settings". There you will have the option to create an OAuth client.
Follow the instructions, and make sure to safely copy the client id and secret.
The latter is only displayed once. More detailed instructions are provided by the
\href{https://documentation.dataspace.copernicus.eu/APIs/SentinelHub/Overview/Authentication.html#registering-oauth-client}{API documentation}
}

\subsection{Client Details as Environment Variables}{

When you share R code, you probably don't want to share your account details.
You can avoid using your \code{client_id} and \code{client_secret} in your script by
setting them as environment variable. You can do this yourself manually by
calling \code{dse_set_client_id()} and \code{dse_set_client_secret()} at the start of each session.

You can download OData simply through https with just you username and
password. You can also store those as environment variables for your convenience.
If you name those \code{CDSE_API_USERNAME} and \code{CDSE_API_PASSWORD} respectively,
they are picked up automatically with \code{\link[=dse_get_username]{dse_get_username()}} and \code{\link[=dse_get_password]{dse_get_password()}}.
OData needs a public access token which is generated with
\code{dse_public_access_token()}, which needs your username and password.

You can also define them in your \code{.Rprofile} file with
\code{Sys.setenv(CDSE_API_CLIENTID = "<your id>")} and
\code{Sys.setenv(CDSE_API_CLIENTSECRET = "<your secret>")}. This way,
they are set each time you start a new R session.

The environment variables are used by default by \code{dse_access_token()},
and \code{dse_public_access_token()} so you
don't have to specify the client details as arguments.
}

\subsection{Obtain Token and Validity}{

After completing the previous two steps, your are now set to obtain an access
token with \code{dse_access_token()}.

Repeatedly requesting an access token may invoke rate limiting measures.
Therefore, this package uses caching to temporarily store the access token
during each R session. Calling \code{dse_access_token()} will therefore only
contact the server once for a token for each unique combination of \code{client_id}
and \code{client_server}. After that, the cached result will be reused during the session

There is a catch: the token provided by the server is only valid for a limited
time (usually 30 minutes). So, when the token has expired, you need to wipe the
cache. You can do so by calling \code{memoise::forget(dse_access_token)} or restarting
the R session.
}
}
\examples{
if (interactive() && dse_has_client_info()) {
  token <- dse_access_token()
}
if (interactive() && dse_has_account()) {
  token_public <- dse_public_access_token()
}
}
\references{
\url{https://documentation.dataspace.copernicus.eu/APIs/SentinelHub/Overview/Authentication.html}
}
\seealso{
\code{\link[=dse_usage]{dse_usage()}}

\code{\link[=dse_user_statistics]{dse_user_statistics()}}

Other authentication:
\code{\link[=dse_get_token_details]{dse_get_token_details()}},
\code{\link[=dse_has_s3_secret]{dse_has_s3_secret()}},
\code{\link[=dse_set_gdal_token]{dse_set_gdal_token()}},
\code{\link[=dse_usage]{dse_usage()}}
}
\concept{authentication}
