googlesheets4: gs4_auth – R documentation

Become an expert in R — Interactive courses, Cheat Sheets, certificates and more!

gs4_auth

Authorize googlesheets4

Description

Authorize googlesheets4 to view and manage your Google Sheets. This function is a wrapper around 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, these user credentials are cached in a folder below your home directory, ~/.R/gargle/gargle-oauth, 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 from a web-based platform, like RStudio Server or Cloud, you need to use a variant of this flow, known as out-of-band auth ("oob"). If this does not happen automatically, you can request it yourself with use_oob = TRUE or, more persistently, by setting an option via options(gargle_oob_default = TRUE).

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

`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, `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 `NA` or `FALSE` to match nothing and force the OAuth dance in the browser. Use `TRUE` to allow email auto-discovery, if exactly one matching token is found in the cache. Defaults to the option named "gargle_oauth_email", retrieved by `gargle_oauth_email()`.
`path`	JSON identifying the service account, in one of the forms supported for the `txt` argument of `jsonlite::fromJSON()` (typically, a file path or JSON string).
`scopes`	A character vector of scopes to request. Pick from those listed at https://developers.google.com/identity/protocols/oauth2/scopes. For certain token flows, the `"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. It is considered a low value scope and does not appear on the consent screen.
`cache`	Specifies the OAuth token cache. Defaults to the option named "gargle_oauth_cache", retrieved via `gargle_oauth_cache()`.
`use_oob`	Whether to prefer "out of band" authentication. Defaults to the option named "gargle_oob_default", retrieved via `gargle_oob_default()`.
`token`	A token with class Token2.0 or an object of httr's class `request`, i.e. a token that has been prepared with `httr::config()` and has a Token2.0 in the `auth_token` component.

Details

Most users, most of the time, do not need to call 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:

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.
Use a service account token.
Bring their own Token2.0.
Specify non-default behavior re: token caching and out-of-bound authentication.

For details on the many ways to find a token, see gargle::token_fetch(). For deeper control over auth, use gs4_auth_configure() to bring your own OAuth app or API key. Read more about gargle options, see gargle::gargle_options.

Examples

if (interactive()) {
  # 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")
}

googlesheets4

Access Google Sheets using the Sheets API V4

v0.3.0

MIT + file LICENSE

Authors

Jennifer Bryan [cre, aut] (<https://orcid.org/0000-0002-6983-2759>), RStudio [cph, fnd]

Initial release