Why do I need an access token?

Access tokens are part of the authentication flow for accessing a resource that lives within Salesforce. Think of it as your way of proving that you are allowed to have access to that resource.

For example, let's say we have a @RestResource REST API endpoint that we have created using Apex. We want to be able to consume the data from that REST API from an external web application.

The web application has to prove that it has access to the Salesforce environment to access the data behind the REST API. This is where access tokens come in.

Many different authorization flows in Salesforce use access tokens. This walkthrough will focus on the username/password auth flow. This is not a viable workflow for a production environment. However, it is a good workflow for testing out HTTP requests quickly.

Postman

Postman is a piece of software that provides a user interface for retrieving access tokens and making HTTP requests.

In this walkthrough, we make use of the Salesforce Platform APIs Collection within Postman, which makes getting an access token relatively straightforward.

We can think of a Postman Collection as a group of pre-configured HTTP requests (GET, POST, etc.)

As such, the Salesforce Platform APIs Collection has many pre-configured requests. However, we are mainly concerned with the access token request.

The steps below will illustrate:

• Adding the Salesforce Platform APIs Collection to Postman

• Making the access token request

• Using the access token

• Troubleshooting for several scenarios

1. Postman Log in / Sign Up

• Head over to postman.com (or use the desktop app)

• Log in to your Postman account (or create a new one)

2. Add and Fork the Collection

• At the top of the page, click the search box

• Search Salesforce Platform APIs

• Click on the collection

• Press the 'Fork' button to fork the collection

• Give the fork a name

• Select a Workspace for the fork

• Press the 'Fork Collection' button

The collection should now be open in your workspace.

3. Request Access Token

Your forked collection should have opened to the 'Authorization' tab.

• Scroll down to the bottom of the Authorization tab

• Leave all default values

• Press the 'Get New Access Token' button

  

• The Salesforce login page will appear in a new window

  • If you are not presented with a standard username/password prompt, see the Troubleshooting section below

• Enter your Salesforce username and password

• Log in

• You should receive the following prompt

• Click 'Allow'

• You will be redirected back to Postman, and should see the following screen

  

• Copy the access token to your clipboard so that we can use it in the next step

• Click the 'Use Token' button

4. Use the Access Token

Now that we have the token, we can use it in a request.

Construct request URL

1. Get your base URL for the request

   

2. Add https:// to the beginning of the base URL

3. Add /<your_api_endpoint_route> to the end of the base URL

For our example, we are using a @RestResource that lives at /services/apexrest/Contacts

Therefore, the full request URL we end up with is:

https://saleshorse-dev-ed.develop.my.salesforce.com/services/apexrest/Contacts

Create a Postman Collection

Chances are, you're going to want to make this same request (or a very similar one) at a later date. And since this request is separate from the access token request, we can store it in a separate Collection.

1. Click the 'Collections' tab in Postman, then click the '+' button

   

2. Click the pencil icon to rename the Collection

   

3. Select 'OAuth 2.0' under the 'Type' dropdown

   

4. Scroll down and paste the access token into the 'Token' field, being sure there is no whitespace

   

5. Add a request to the collection by expanding the collection in the sidebar and clicking the 'Add a request' link (or by pressing the three dots (...) and selecting 'Add request')

   

6. Rename the request from the default 'New Request'

   

7. Select the 'Authorization' tab, and ensure that 'Inherit auth from parent' is selected as the 'Type'. (Because we entered the token for the entire collection, we don't have to enter it again for each request within that collection)

   

8. Paste in the request URL and press 'Send'

   

9. The request result appears at the bottom of the window

   

10. Save the Collection

    

Troubleshooting

Trouble getting access token

If a list of saved usernames appears, click the 'Log in with a Different Username' link.

• The Salesforce login page will appear in a new window

  • If the URL in the new window starts with login.salesforce.com

    • Click the 'Use Custom Domain' link

      

  • If the URL in the new window is the URL of your target Salesforce org, skip this step and enter your username and password (the 'Use Custom Domain' link will not be present)

Find your domain URL

• Log into the Salesforce org that you are requesting an access token for

• Click on your avatar in the top-right

• Copy the URL up until the .my.salesforce.com

  

• Paste it into the 'Custom Domain' field (Salesforce automatically adds the .my.salesforce.com

  

• Press 'Continue'

• Log in with your username and password

Trouble using access token

If you receive the following error when using the access token in a request, follow the steps below to resolve the issue:

{
    "message": "Session expired or invalid",
    "errorCode": "INVALID_SESSION_ID"
  }

Request another token

Access tokens are only valid for a limited time, so you may just be seeing this message because you need to request a fresh token to use in your request.

Check that the token was copied and pasted correctly

You may have missed a character when highlighting the access token. Request a new token, and make sure that is not the issue.

If you are sure you have copied the token correctly, check that there are no line breaks or leading/trailing spaces in the access token.

In the screenshot above, Postman is trying to hint to us that we have a line break at the end of our token, by displaying a carriage return symbol (highlighted in red).

To fix this, place your cursor on the empty line below the token, then press the backspace key. You should see the token input shrink to fit the length of your token, and the carriage return symbol should go away:

Make sure the token was requested for the correct Salesforce org

TL;DR -- log out of any logged-in Salesforce sessions, and request the token again

If you frequently log into more than one Salesforce org, you may run into this issue.

When you log into a Salesforce org, it creates a session within your browser. This is why you can click a link for a record in that Salesforce org and be taken straight to the record, without having to log in.

If you are using the Postman web application in the same browser session as the Salesforce org you are logged into, Postman is going to request the access token for the org you're already logged into.

If the org you're already logged into isn't the org you're requesting the access token for, this isn't the behavior you want.

If you're still scratching your head, let's work through an example:

Say your company uses Salesforce internally for things like showing company news and events. You logged into the internal Salesforce org when you started your day, looked over the announcements, then started working on integrating a REST API endpoint for a client, which lives in the client's Salesforce org.

When you request the access token with Postman through the Postman web app in the browser, the steps go something like this:

1. Postman requests an access token from the Salesforce access token endpoint. (Note that this endpoint is not specific to any one org)

2. Salesforce says "I might have a token for you, but first I need you to tell me who you are", and attempts to relay this message back to Postman through the browser

3. But before that "who are you?" message can even get back to Postman your browser session butts in and says, "No need! Check it out, they're already logged in."

4. Salesforce says "Whatever. Here's your token."

5. You are then issued a token for the incorrect org, because you never got the chance to specify which org you wanted the token for

To get around this issue, you can either:

1. Log out of the Salesforce org in your current browser session

2. Go to Postman in a private/incognito browser window to force a new session

After picking one of the two options, request a new token via Postman, and enter the credentials for the desired org when prompted.