sf_auth {salesforcer}

Log in to Salesforce

Description

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.

Usage

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

## Not run: 
# log in using basic authentication (username-password)
sf_auth(username = "[e-mail]", 
        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")

## End(Not run)