credentials_user_oauth2: Get an OAuth token for a user

View source: R/credentials_user_oauth2.R

credentials_user_oauth2R Documentation

Get an OAuth token for a user


Consults the token cache for a suitable OAuth token and, if unsuccessful, gets a token via the browser flow. A cached token is suitable if it's compatible with the user's request in this sense:

  • OAuth client must be same.

  • Scopes must be same.

  • Email, if provided, must be same. If specified email is a glob pattern like "*", email matching is done at the domain level.

gargle is very conservative about using OAuth tokens discovered in the user's cache and will generally seek interactive confirmation. Therefore, in a non-interactive setting, it's important to explicitly specify the "email" of the target account or to explicitly authorize automatic discovery. See gargle2.0_token(), which this function wraps, for more. Non-interactive use also suggests it might be time to use a service account token or workload identity federation.


  scopes = NULL,
  client = gargle_client(),
  package = "gargle",
  app = deprecated()



A character vector of scopes to request. Pick from those listed at

For certain token flows, the "" 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.


A Google OAuth client, preferably constructed via gargle_oauth_client_from_json(), which returns an instance of gargle_oauth_client. For backwards compatibility, for a limited time, gargle will still accept an "OAuth app" created with httr::oauth_app().


Name of the package requesting a token. Used in messages.


Arguments passed on to gargle2.0_token


Optional. If specified, email can take several different forms:

  • "", 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, 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).

  • "*", i.e. a domain-only glob pattern. This can be helpful if you need code that "just works" for both and

  • TRUE means that you are approving email auto-discovery. If exactly one matching token is found in the cache, it will be used.

  • FALSE or NA mean that you want to ignore the token cache and force a new OAuth dance in the browser.

Defaults to the option named "gargle_oauth_email", retrieved by gargle_oauth_email() (unless a wrapper package implements different default behavior).


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 gargle_oob_default(). Note that (pseudo-)OOB auth only affects the initial OAuth dance. If we retrieve (and possibly refresh) a cached token, 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 gargle_oauth_client_type(). You can take control of the client type by setting options(gargle_oauth_client_type = "web") or options(gargle_oauth_client_type = "installed").


Specifies the OAuth token cache. Defaults to the option named "gargle_oauth_cache", retrieved via gargle_oauth_cache().


Advanced use only: allows you to completely customise token generation.


[Deprecated] Replaced by the client argument.


A Gargle2.0 token.

See Also

Other credential functions: credentials_app_default(), credentials_byo_oauth2(), credentials_external_account(), credentials_gce(), credentials_service_account(), token_fetch()


## Not run: 
# Drive scope, built-in gargle demo client
scopes <- ""
credentials_user_oauth2(scopes, client = gargle_client())

# bring your own client
client <- gargle_oauth_client_from_json(
  path = "/path/to/the/JSON/you/downloaded/from/gcp/console.json",
  name = "my-nifty-oauth-client"
credentials_user_oauth2(scopes, client)

## End(Not run)

ropenscilabs/gauth documentation built on Sept. 11, 2023, 6:20 a.m.