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.

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



optional; an actual token object or the path to a valid token stored as an .rds file


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.


the "Client ID" for the application


logical indicating if mermaidr should cache credentials in the default cache file .httr-oauth


logical; do you want informative messages?


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:


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.


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

# 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