% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/gads_auth.R
\name{gads_auth}
\alias{gads_auth}
\title{Authorization in Google Ads API}
\usage{
gads_auth(
  email = gargle::gargle_oauth_email(),
  path = NULL,
  cache = gargle::gargle_oauth_cache(),
  use_oob = gargle::gargle_oob_default(),
  developer_token = getOption("gads.developer.token"),
  token = NULL
)
}
\arguments{
\item{email}{Optional. Allows user to target a specific Google identity.}

\item{path}{Path to JSON file with identifying the service account}

\item{cache}{Specifies the OAuth token cache.}

\item{use_oob}{Whether to prefer "out of band" authentication.}

\item{developer_token}{Your Google Ads Developer Token.}

\item{token}{A token with class \link[httr:Token-class]{Token2.0} or an object of}
}
\value{
\link[httr:Token-class]{Token2.0}
}
\description{
Authorize rgoogleads to view and manage your Google Ads Account. 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 rgoogleads permission to operate on your
behalf with Google Ads. 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{gads_auth()}
explicitly -- it is triggered by the first action that requires
authorization. Even when called, the default arguments often suffice.

However, when necessary, \code{gads_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[=gads_auth_configure]{gads_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{
\dontrun{
## load/refresh existing credentials, if available
## otherwise, go to browser for authentication and authorization
gads_auth()

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

## force a menu where you can choose from existing tokens or
## choose to get a new one
gads_auth(email = NA)

## -----------------------
## use own developer token
gads_auth(
    email = "yourname@example.com",
    developer_token = "your developer token"
)

## -----------------------
## use own OAuth client app
gads_auth_configure(
    path = "path/to/your/oauth_client.json"
)

gads_auth(email = "yourname@example.com")
}
}
\seealso{
Other auth functions: 
\code{\link{gads_auth_configure}()},
\code{\link{gads_deauth}()}
}
\concept{auth functions}
