Salesforce OAuth Access Token For Command Line Access to REST API

November 15, 2016

Working with the Salesforce OAuth and Salesforce Force.com REST API

Picture of cat representing salesforce oauth for rest api

Recently, I had to add some code to a Rails application to create a Contact via the Salesforce API when another action happened in a Rails controller. Essentially this meant I couldn’t use the traditional three-legged OAuth flow. I needed to provide credentials and get an access token to allow me to issue commands via the Salesforce REST API. The first thing on my plate to do for this tasker was to try and do it via the cURL command line tool.

How the authentication flow works with cURL:

This process is for “Session ID Authorization” as outlined in https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/quickstart_oauth.htm

Step 1 – setup a connected app (or use an existing one such as Jazz) to get the clientsecret and client_id (called _consumer_secret and consumer_key in Salesforce)

Step 2 – Issue a cURL request with the following format to get the access_token:

curl https://test.salesforce.com/services/oauth2/token -H "application/x-www-form-urlencoded" -d "grant_type=password" -d "client_id=XXXXX" -d "client_secret=12345YYYY" -d "username=username@example.com" -d "password=<salesforce_password><security_token>"

Note that password above is your salesforce password concatenated with your security token (obtained by clicking Reset Security Token in the Salesforce interface). Also, in production, you would use https://login.salesforce.com as the URL to fetch the access token from instead of https://test.salesforce.com.

You will get back an access token in a response similar to below:

Step 3 – issue another cURL request with the access_token obtained from Step 2 to the salesforce REST API (example below creates a contact)

Example access_token

{"access_token":"BY123!xxx","instance_url":"https://ap1.salesforce.com","id":"https://test.salesforce.com/id/0012300Cv0TEASE/005101XbnABC","token_type":"Bearer","issued_at":"1478998365476","signature":"xpzzzYYMs6pC0M7BzRR+BdzN9O/N34VVVCaUuU0="}

Example of creating a contact

When you make a call to the Salesforce API, you will use the instance url from the access token response in the above example.

curl "https://ap1.salesforce.com/services/data/v20.0/sobjects/Contact/" -H "Authorization: Bearer BY123!xxx" -H "Content-Type: application/json; charset=UTF-8" -d '{"lastname": "TestExample", "email": "test@example.com"}'

Pitfalls

  • Note in the above example there is an exclamation point in the access token. When issuing a cURL command in bash shell, there is a “history expansion” going on. If you try to escape the “!” with a “”, you will get an INVALID_SESSION_ID error.
  • 2 workarounds: Issue the cURL request through Postman chrome plugin/app OR turn off history expansion in your shell.

Token expiration

The token expires according to your Organization’s default settings in Salesforce.

Once you have the token, you can now issue commands to the Salesforce Force.com REST API.


Profile picture

Written by Bruce Park who lives and works in the USA building useful things. He is sometimes around on Twitter.