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
2. Add and Fork the Collection
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
Get your base URL for the request
Add https:// to the beginning of the base URL
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.
Click the 'Collections' tab in Postman, then click the '+' button
Click the pencil icon to rename the Collection
Select 'OAuth 2.0' under the 'Type' dropdown
Scroll down and paste the access token into the 'Token' field, being sure there is no whitespace
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')
Rename the request from the default 'New Request'
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)
Paste in the request URL and press 'Send'
The request result appears at the bottom of the window
Save the Collection
Troubleshooting
Trouble getting access token
If a list of saved usernames appears, click the 'Log in with a Different Username' link.
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:
Postman requests an access token from the Salesforce access token endpoint. (Note that this endpoint is not specific to any one org)
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
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."
Salesforce says "Whatever. Here's your token."
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:
Log out of the Salesforce org in your current browser session
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.
