% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/gs4_auth.R
\name{gs4_auth}
\alias{gs4_auth}
\title{Authorize googlesheets4}
\usage{
gs4_auth(
  email = gargle::gargle_oauth_email(),
  path = NULL,
  scopes = "https://www.googleapis.com/auth/spreadsheets",
  cache = gargle::gargle_oauth_cache(),
  use_oob = gargle::gargle_oob_default(),
  token = NULL
)
}
\arguments{
\item{email}{Optional. Allows user to target a specific Google identity. If
specified, this is used for token lookup, i.e. to determine if a suitable
token is already available in the cache. If no such token is found, \code{email}
is used to pre-select the targetted Google identity in the OAuth chooser.
Note, however, that the email associated with a token when it's cached is
always determined from the token itself, never from this argument. Use \code{NA}
or \code{FALSE} to match nothing and force the OAuth dance in the browser. Use
\code{TRUE} to allow email auto-discovery, if exactly one matching token is
found in the cache. Specify just the domain with a glob pattern, e.g.
\code{"*@example.com"}, to create code that "just works" for both
\code{alice@example.com} and \code{bob@example.com}. Defaults to the option named
"gargle_oauth_email", retrieved by \code{\link[gargle:gargle_oauth_email]{gargle_oauth_email()}}.}

\item{path}{JSON identifying the service account, in one of the forms
supported for the \code{txt} argument of \code{\link[jsonlite:fromJSON]{jsonlite::fromJSON()}} (typically, a
file path or JSON string).}

\item{scopes}{A character vector of scopes to request. Pick from those listed
at \url{https://developers.google.com/identity/protocols/oauth2/scopes}.

For certain token flows, the
\code{"https://www.googleapis.com/auth/userinfo.email"} scope is unconditionally
included. This grants permission to retrieve the email address associated
with a token; gargle uses this to index cached OAuth tokens. This grants no
permission to view or send email and is generally considered a low-value
scope.}

\item{cache}{Specifies the OAuth token cache. Defaults to the option named
\code{"gargle_oauth_cache"}, retrieved via \code{\link[gargle:gargle_oauth_cache]{gargle_oauth_cache()}}.}

\item{use_oob}{Whether to prefer out-of-band authentication. Defaults to the
value returned by \code{\link[gargle:gargle_oob_default]{gargle_oob_default()}}.}

\item{token}{A token with class \link[httr:Token-class]{Token2.0} or an object of
httr's class \code{request}, i.e. a token that has been prepared with
\code{\link[httr:config]{httr::config()}} and has a \link[httr:Token-class]{Token2.0} in the
\code{auth_token} component.}
}
\description{
Authorize googlesheets4 to view and manage your Google Sheets. This function is a
wrapper around \code{\link[gargle:token_fetch]{gargle::token_fetch()}}.

By default, you are directed to a web browser, asked to sign in to your
Google account, and to grant googlesheets4 permission to operate on your
behalf with Google Sheets. By default, with your permission, these user
credentials are cached in a folder below your home directory, from where
they can be automatically refreshed, as necessary. Storage at the user
level means the same token can be used across multiple projects and
tokens are less likely to be synced to the cloud by accident.

If you are interacting with R within a browser (applies to RStudio Server,
Posit Workbench, and Posit Cloud), you need a variant of this flow,
known as out-of-band auth ("oob"). If this does not happen
automatically, you can request it yourself with \code{use_oob = TRUE} or,
more persistently, by setting an option via
\code{options(gargle_oob_default = TRUE)}.
}
\details{
Most users, most of the time, do not need to call \code{gs4_auth()}
explicitly -- it is triggered by the first action that requires
authorization. Even when called, the default arguments often suffice.
However, when necessary, this function allows the user to explicitly:
\itemize{
\item Declare which Google identity to use, via an email address. If there
are multiple cached tokens, this can clarify which one to use. It can
also force googlesheets4 to switch from one identity to another. If
there's no cached token for the email, this triggers a return to the
browser to choose the identity and give consent. You can specify just
the domain by using a glob pattern. This means that a script
containing \code{email = "*@example.com"} can be run without further
tweaks on the machine of either \code{alice@example.com} or
\code{bob@example.com}.
\item Use a service account token or workload identity federation.
\item Bring their own \link[httr:Token-class]{Token2.0}.
\item Specify non-default behavior re: token caching and out-of-bound
authentication.
\item Customize scopes.
}

For details on the many ways to find a token, see
\code{\link[gargle:token_fetch]{gargle::token_fetch()}}. For deeper control over auth, use
\code{\link[=gs4_auth_configure]{gs4_auth_configure()}} to bring your own OAuth client or API key.
Read more about gargle options, see \link[gargle:gargle_options]{gargle::gargle_options}.
}
\examples{
\dontshow{if (rlang::is_interactive()) (if (getRversion() >= "3.4") withAutoprint else force)(\{ # examplesIf}
# load/refresh existing credentials, if available
# otherwise, go to browser for authentication and authorization
gs4_auth()

# force use of a token associated with a specific email
gs4_auth(email = "jenny@example.com")

# use a 'read only' scope, so it's impossible to edit or delete Sheets
gs4_auth(
  scopes = "https://www.googleapis.com/auth/spreadsheets.readonly"
)

# use a service account token
gs4_auth(path = "foofy-83ee9e7c9c48.json")
\dontshow{\}) # examplesIf}
}
\seealso{
Other auth functions: 
\code{\link{gs4_auth_configure}()},
\code{\link{gs4_deauth}()}
}
\concept{auth functions}
