Authorize mermaidr — mermaid

Authorize mermaidr to access the MERMAID API. You will be directed to a web browser and asked to sign in to MERMAID Collect. By default, these user credentials are cached in a file named .httr-oauth in the current working directory, from where they can be automatically refreshed, as necessary.

mermaid_auth(
  token = NULL,
  new_user = FALSE,
  key = mermaid_key,
  cache = getOption("mermaidr.httr_oauth_cache"),
  verbose = TRUE
)

Arguments

token: optional; an actual token object or the path to a valid token stored as an .rds file
new_user: logical, defaults to FALSE. Set to TRUE if you want to wipe the slate clean and re-authenticate with the same or different account. This disables the .httr-oauth file in current working directory.
key: the "Client ID" for the application
cache: logical indicating if mermaidr should cache credentials in the default cache file .httr-oauth
verbose: logical; do you want informative messages?

Details

Most users, most of the time, do not need to call this function explicitly – it will be triggered by the first action that requires authorization. Even when called, the default arguments will often suffice. However, when necessary, this function allows the user to

force the creation of a new token
retrieve current token as an object, for possible storage to an .rds file
read the token from an object or from an .rds file
prevent caching of credentials in .httr-oauth

In a direct call to mermaid_auth, the user can dictate whether interactively-obtained credentials will be cached in .httr_oauth. If unspecified, these arguments are controlled via options, which, if undefined at the time mermaidr is loaded, are defined like so:

cache: Set to option mermaidr.httr_oauth_cache, which defaults to TRUE

To override these defaults in persistent way, predefine one or more of them with lines like this in a .Rprofile file:


options(mermaidr.httr_oauth_cache = FALSE)

See Startup for possible locations for this file and the implications thereof.

Examples

if (FALSE) { # \dontrun{
# Load/refresh existing credentials, if available
# Otherwise, go to browser for authentication and authorization
mermaid_auth()

# Force a new token to be obtained
mermaid_auth(new_user = TRUE)

# Store token in an object and then to file
ttt <- mermaid_auth()
saveRDS(ttt, "ttt.rds")

# Load a pre-existing token
mermaid_auth(token = ttt) # from an object
mermaid_auth(token = "ttt.rds") # from .rds file
} # }