Log in to Salesforce — sf_auth • salesforcer

Log in using Basic (Username-Password) or OAuth 2.0 authentication. OAuth does not require sharing passwords, but will require authorizing salesforcer as a connected app to view and manage your organization. You will be directed to a web browser, asked to sign in to your Salesforce account, and to grant salesforcer permission to operate on your behalf. By default, these user credentials are cached in a file named .httr-oauth-salesforcer in the current working directory.

sf_auth(
  username = NULL,
  password = NULL,
  security_token = NULL,
  login_url = getOption("salesforcer.login_url"),
  token = NULL,
  consumer_key = getOption("salesforcer.consumer_key"),
  consumer_secret = getOption("salesforcer.consumer_secret"),
  callback_url = getOption("salesforcer.callback_url"),
  cache = getOption("salesforcer.httr_oauth_cache"),
  verbose = FALSE
)

Arguments

username: Salesforce username, typically an email address
password: Salesforce password
security_token: Salesforce security token. Note: A new security token is generated whenever your password is changed.
login_url: a custom login url; defaults to https://login.salesforce.com. If needing to log into a sandbox or dev environment then provide its login URL (e.g. https://test.salesforce.com)
token: optional; an actual token object or the path to a valid token stored as an .rds file
consumer_key, consumer_secret, callback_url: the "Consumer Key","Consumer Secret", and "Callback URL" when using a connected app; defaults to the salesforcer connected apps' consumer key, secret, and callback url
cache: logical or character; TRUE means to cache using the default cache file .httr-oauth-salesforcer, FALSE means do not cache. A string means use the specified path as the cache file.
verbose: logical; an indicator of whether to print additional detail for each API call, which is useful for debugging. More specifically, when set to TRUE the URL, header, and body will be printed for each request, along with additional diagnostic information where available.

Value

list invisibly that contains 4 elements detailing the authentication state

Note

The link{sf_auth} function invisibly returns the following 4 pieces of information which can be reused in other operations:

auth_method: character; One of two options 'Basic' or 'OAuth'. If a username, password, and security token were supplied, then this would result in 'Basic' authentication.
token: Token2.0; The object returned by oauth2.0_token. This value is NULL if auth_method='Basic'.
session_id: character; A unique ID associated with this user session. The session ID is obtained from the X-SFDC-Session header fetched with SOAP API's login() call. This value is NULL if auth_method='OAuth'.
instance_url: character; The domain address of the server that your Salesforce org is on and where subsequent API calls will be directed to. For example, https://na21.salesforce.com refers to an org located on the 'NA21' server instance located in Chicago, USA / Washington DC, USA per this Knowledge Article: https://help.salesforce.com/s/articleView?language=en_US&id=000314281.

Examples

if (FALSE) {
# log in using basic authentication (username-password)
sf_auth(username = "test@gmail.com", 
        password = "test_password", 
        security_token = "test_token")

# log in using OAuth 2.0 (via browser or cached .httr-oauth-salesforcer)
sf_auth()

# log in to a Sandbox environment
# Via brower or refresh of .httr-oauth-salesforcer
sf_auth(login_url = "https://test.salesforce.com")

# Save token to disk and log in using it
saveRDS(salesforcer_state()$token, "token.rds")
sf_auth(token = "token.rds")
}