The easiest way to connect to the SalesForce API

This post is a simple reminder of how to simply get going connecting to Salesforce using the API. The security model is very rich and the documentation is sadly both lacking and, in some cases, wrong. I therefore took it upon me to create a “How to get to the first successful message” post.
Any additional information can be found in the Salesforce documentation.

Note that the security might not be optimal for your needs down the line in your use of Salesforce. Personally, I used the API to upload Account and Contact data and the let loose the salespeople on the application.

The steps are these:

  1. Make sure you have access to Salesforce.
  2. Make sure you are a Systems Admin.
  3. Setup a Connected Application, this is the connection used for the API calls.
  4. Getting some user info
  5. Getting your Security Token
  6. Login and get an access token.
  7. Test the access token using a standard call.

I will use the simple Username and Password flow. There are others, but this seems to fit my needs the best.

Here we go.

Make sure you have access to Salesforce

You have been assigned a user and a path for login. Usually this is login.salesforce.com or test.salesforce.com if you are using the sandbox.

Make sure you are a Systems Admin

Access the Setup part of Salesforce. This is usually done by clicking the cogs up to the right of the screen.

A new tab will open with all the settings.

Access the “Users” setting by clicking the menu to the left under Administration. Click Users and the Users again.

In the list to the right, find your identity and make sure it is System Administrator.

Setup a connected Application

In the menu to the left find the Platform Tools heading. Click Apps and then App Manager

The list to the right contains all the currently connected apps. Ignore that and look for the button saying New Connected App. It is up to the right. Click it.

Time to fill in the fields.

Connected App name: A name you choose. Can be anything.

API Name: Auto fills. Do not touch it.

Contact e-mail: Fill in a valid e-mail that you have access to.

Scroll down and choose Enable OAuth Settings.

Now comes the tricky part. Looking at the documentation you should fill in … well it does not really say there but the path is https://login.salesforce.com/services/oauth2/callback. If you are using the sandbox (or test-version) the address is https://test.salesforce.com/services/oauth2/callback.

Lastly set the OAuth Scope to the level you need. To be sure it gets all the access it needs, simple choose Full Access and click Add to the right.

Now you are done. Click to Save and the wait for instructions to wait.

Getting some user info

In order to access the API you need the application’s Consumer Key and Consumer Secret. You can get them by looking at the app you just created.

Go back to the App Manager Page and find you App in the list to the right. Look to the far right of that row and click the “down arrow”, choose View.

There are two values here that you need to copy, the consumer key (usually a very long text string of gibberish) and then your Consumer secret, usually a string of numbers.

Getting your security token

This is a token that is used to verify your password when you call to login to the API. There might be a way of getting it without resetting it (as per the instructions below) but it will at least work.

Open your own personal page (up to the right) and click settings.

I the menu to the left find the item “Reset My Security Token”

Click it and the click the Reset Security Token button.

A new token will be sent to you in a minute. Continue with the instructions here and wait for it.

Login and get an access token

Time to put all this to good use. I personally use Postman to test the API. Here is how you should configure the POST to make sure you get the access token back.

Method: POST

Headers

Content-Type: application/x-www-form-urlencoded

URL: https://login.salesforce.com/services/oauth2/token or https://test.salesforce.com/services/oauth2/token if you are using the Sandbox.

Then you need to add the following params to your URL string.

grant_type:password

client_id: The Consumer Key you copied above

client_secret: The Consumer Secret you copied above

username: Your username that you used to log into Salesforce. Note! If you are using an e-mail address you should escape the @-sign as %40. So, if your username is mikael_sand@salesforce.com it should be formatted as mikael_sand%40salesforce.com

password: The password you used to log into Salesforce and then add the security key that was e-mailed to you.

Now you are ready log in. Click Send in Postman and if it works, you will get back some nice JSON with an access-token.

Test the access token using a standard call

Now to test that the access token works.

Simply send configure Postman like this:

Method: GET

Headers

Authorization: Bearer [the access-token above] (Note that there is a space between “Bearer” and the token.

URL: Here you need to know what instance of Salesforce you are running on. This is suppled in the authorization call above in a JSON property called “instance_url”.

The path for getting information on the Account object is this: https://instance_url/services/data/v39.0/sobjects/Account/describe. The v39.0 may shift, this is the latest version at the time of writing.

Click send and you should get back some nice JSON describing the fields of the Account object.

Errors?

If you get back an error like “Session Expired or Invalid” make sure that:

  1. You send the call to the correct instance url (test vs prod got me here).
  2. You send the correct access token in the Authorization header (got me once).