% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/drive_auth.R
\name{drive_auth}
\alias{drive_auth}
\title{Authorize googledrive}
\usage{
drive_auth(
  email = gargle::gargle_oauth_email(),
  path = NULL,
  subject = NULL,
  scopes = "drive",
  cache = gargle::gargle_oauth_cache(),
  use_oob = gargle::gargle_oob_default(),
  token = NULL
)
}
\arguments{
\item{email}{Optional. If specified, \code{email} can take several different
forms:
\itemize{
\item \code{"jane@gmail.com"}, i.e. an actual email address. This allows the 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 targeted
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).
\item \code{"*@example.com"}, i.e. a domain-only glob pattern. This can be helpful if
you need code that "just works" for both \code{alice@example.com} and
\code{bob@example.com}.
\item \code{TRUE} means that you are approving email auto-discovery. If exactly one
matching token is found in the cache, it will be used.
\item \code{FALSE} or \code{NA} mean that you want to ignore the token cache and force a
new OAuth dance in the browser.
}

Defaults to the option named \code{"gargle_oauth_email"}, retrieved by
\code{\link[gargle:gargle_oauth_email]{gargle_oauth_email()}} (unless a wrapper package implements different
default behavior).}

\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{subject}{An optional subject claim. Specify this if you wish to use the
service account represented by \code{path} to impersonate the \code{subject}, who is
a normal user. Before this can work, an administrator must grant the service
account domain-wide authority. Identify the user to impersonate via their
email, e.g. \code{subject = "user@example.com"}. Note that gargle automatically
adds the non-sensitive \code{"https://www.googleapis.com/auth/userinfo.email"}
scope, so this scope must be enabled for the service account, along with
any other \code{scopes} being requested.}

\item{scopes}{One or more API scopes. Each scope can be specified in full or,
for Drive API-specific scopes, in an abbreviated form that is recognized by
\code{\link[=drive_scopes]{drive_scopes()}}:
\itemize{
\item "drive" = "https://www.googleapis.com/auth/drive" (the default)
\item "full" = "https://www.googleapis.com/auth/drive" (same as "drive")
\item "drive.readonly" = "https://www.googleapis.com/auth/drive.readonly"
\item "drive.file" = "https://www.googleapis.com/auth/drive.file"
\item "drive.appdata" = "https://www.googleapis.com/auth/drive.appdata"
\item "drive.metadata" = "https://www.googleapis.com/auth/drive.metadata"
\item "drive.metadata.readonly" = "https://www.googleapis.com/auth/drive.metadata.readonly"
\item "drive.photos.readonly" = "https://www.googleapis.com/auth/drive.photos.readonly"
\item "drive.scripts" = "https://www.googleapis.com/auth/drive.scripts
}

See \url{https://developers.google.com/drive/api/guides/api-specific-auth} for
details on the permissions for each 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 use out-of-band authentication (or, perhaps, a
variant implemented by gargle and known as "pseudo-OOB") when first
acquiring the token. Defaults to the value returned by
\code{\link[gargle:gargle_oob_default]{gargle_oob_default()}}. Note that (pseudo-)OOB auth only affects
the initial OAuth dance. If we retrieve (and possibly refresh) a
cached token, \code{use_oob} has no effect.

If the OAuth client is provided implicitly by a wrapper package, its type
probably defaults to the value returned by
\code{\link[gargle:gargle_oauth_client_type]{gargle_oauth_client_type()}}. You can take control of the client
type by setting \code{options(gargle_oauth_client_type = "web")} or
\code{options(gargle_oauth_client_type = "installed")}.}

\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 googledrive to view and manage your Drive files. 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 googledrive permission to operate on your
behalf with Google Drive. 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.
}
\details{
Most users, most of the time, do not need to call \code{drive_auth()}
explicitly -- it is triggered by the first action that requires
authorization. Even when called, the default arguments often suffice.

However, when necessary, \code{drive_auth()} allows the user to explicitly:
\itemize{
\item Declare which Google identity to use, via an \code{email} specification.
\item Use a service account token or workload identity federation via
\code{path}.
\item Bring your own \code{token}.
\item Customize \code{scopes}.
\item Use a non-default \code{cache} folder or turn caching off.
\item Explicitly request out-of-band (OOB) auth via \code{use_oob}.
}

If you are interacting with R within a browser (applies to RStudio
Server, Posit Workbench, Posit Cloud, and Google Colaboratory), you need
OOB auth or the pseudo-OOB variant. If this does not happen
automatically, you can request it explicitly with \code{use_oob = TRUE} or,
more persistently, by setting an option via
\code{options(gargle_oob_default = TRUE)}.

The choice between conventional OOB or pseudo-OOB auth is determined
by the type of OAuth client. If the client is of the "installed" type,
\code{use_oob = TRUE} results in conventional OOB auth. If the client is of
the "web" type, \code{use_oob = TRUE} results in pseudo-OOB auth. Packages
that provide a built-in OAuth client can usually detect which type of
client to use. But if you need to set this explicitly, use the
\code{"gargle_oauth_client_type"} option:

\if{html}{\out{<div class="sourceCode r">}}\preformatted{options(gargle_oauth_client_type = "web")       # pseudo-OOB
# or, alternatively
options(gargle_oauth_client_type = "installed") # conventional OOB
}\if{html}{\out{</div>}}

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[=drive_auth_configure]{drive_auth_configure()}} to bring your own OAuth client or API key.
To learn more about gargle options, see \link[gargle:gargle_options]{gargle::gargle_options}.
}
\examples{
\dontshow{if (rlang::is_interactive()) withAutoprint(\{ # examplesIf}
# load/refresh existing credentials, if available
# otherwise, go to browser for authentication and authorization
drive_auth()

# see user associated with current token
drive_user()

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

# force the OAuth web dance
drive_auth(email = NA)

# use a 'read only' scope, so it's impossible to edit or delete files
drive_auth(scopes = "drive.readonly")

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