Salesforce Auth Provider
At this time, Arcade does not offer a default Salesforce Auth Provider and cannot support Salesforce auth in the Arcade Cloud. To use Salesforce auth, the Salesforce toolkit, or to develop your custom Salesforce tools, you must self-host the Arcade Engine and create a custom Auth Provider with your own Salesforce OAuth 2.0 credentials as described below.
The Salesforce auth provider enables tools and agents to call Salesforce APIs on behalf of a user. Behind the scenes, the Arcade Engine and the Salesforce auth provider seamlessly manage Salesforce OAuth 2.0 authorization for your users.
What’s documented here
This page describes how to use and configure Salesforce auth with Arcade.
This auth provider is used by:
- The Arcade Salesforce toolkit, which provides pre-built tools for interacting with Salesforce services
- Your app code that needs to call Salesforce APIs
- Or, your custom tools that need to call Salesforce APIs
Create a Salesforce app
Salesforce has two types of apps: Connected App and Lightning App. For this guide, we’ll create a Connected App. Make sure to follow the instructions below while you create your Connected App.
When creating your app, make sure to:
- Under “API (Enable OAuth Settings)”, check the Enable OAuth Settings box
- Set the callback URL to:
https://cloud.arcade.dev/api/v1/oauth/callback
- In the Available OAuth Scopes, add the two following scopes:
- “Manage User Data Via APIs (api)”
- “Perform requests at any time (refresh_token, offline_access)”
- Uncheck the Require Proof Key for Code Exchange (PKCE) option, unless you want to use PKCE (in which case, you’ll also need to enable PKCE in the Salesforce auth configuration as described below)
- Check “Enable Token Exchange Flow”
- Check “Enable Refresh Token Rotation”
- Leave all other settings as default and save your app
Right after creating the app, Salesforce will redirect you to the app’s page. In the “API (Enable OAuth Settings)” section, click on the Manage Consumer Details button and take note of the API Key and Client Secret values.
Then, go back to the App’s page and click on the Manage button at the top, then click on the Edit Policies button, at the top of the Manage page, and follow the instructions below:
- In “IP Relaxation”, select Relax IP Restrictions.
- In “Refresh Token Policy”, make sure the option Refresh token is valid until revoked is checked.
With that, your Salesforce app is ready to be used with Arcade.
Get your Salesforce Org Subdomain
Follow the steps below to find your Salesforce Org Subdomain:
- In the Setup menu, click on Quick Find in the top left corner and type
"my domain"
. - In the search results, under Company Settings, click on My Domain.
- Under My Domain Details, check the value of the Current My Domain URL field.
Your Salesforce Org Subdomain is the value before the .my.salesforce.com
part. For example, if your Salesforce domain is https://acme-inc.my.salesforce.com
, your Salesforce Org Subdomain is acme-inc
. If you have a developer account, your URL might look like https://acme-inc.develop.my.salesforce.com
. In this case, your Salesforce Org Subdomain is acme-inc.develop
.
Take note of your Salesforce Org Subdomain. You will need this value in the next steps.
Set the Salesforce Org Subdomain Environment Variable
Refer to the previous step to find your Salesforce Org Subdomain.
Set the SALESFORCE_ORG_SUBDOMAIN
environment variable in the same runtime where your Arcade Worker is executed:
export SALESFORCE_ORG_SUBDOMAIN={your-salesforce-subdomain}
Create and Assign Custom Scopes to your Connected App
The Salesforce API requires the App developer to create OAuth custom scopes defining granular permissions for their application users to authorize.
The custom scopes required by the Arcade Salesforce toolkit are listed below, along with their descriptions:
The custom scopes listed below are only required if you are using the Arcade Salesforce toolkit.
If you’re creating your own custom Salesforce tools or using Arcade to authorize users and call Salesforce APIs directly, you are free to define custom scope(s) that fit best your application use cases. Observe that you must have at least one custom scope assigned to your Salesforce app in order to use the Salesforce API.
read_account
: Read access to account data.read_contact
: Read access to contact data.read_lead
: Read access to lead data.read_note
: Read access to note data.read_opportunity
: Read access to opportunity data.read_task
: Read access to task data.write_contact
: Write access to create contact.
Follow the Create an OAuth Custom Scope and Assign an OAuth Custom Scope to a Connected App Salesforce documentation to understand how to define and assign these scopes to your Salesforce app.
The scope names aren’t really attached to any endpoint or action. It’s the developer’s job to honor the permissions communicated to the user when authorizing the app. You could, in theory, assign one single scope (e.g. fullaccess
) and use it to query any Salesforce API endpoint.
Configuring Salesforce Auth
Refer to Installing Arcade Locally for more information on how to install and run the Arcade Engine.
You can either configure Salesforce auth from the Arcade Engine Dashboard graphical interface or in the engine.yaml
file. We describe both options below.
Configure Salesforce Auth Using the Arcade Dashboard GUI
Access the Arcade Dashboard
By default, the Arcade Dashboard will be available at http://localhost:9099/dashboard
(if you’re accessing it from the same machine where it’s running). Change the host and port number to match your environment.
Navigate to the OAuth Providers page
- Under the OAuth section of the Arcade Dashboard left-side menu, click Providers.
- Click Add OAuth Provider in the top right corner.
- Select the Custom Provider tab at the top.
Enter the provider details
- Enter
salesforce
as the ID for your provider (the ID must besalesforce
in order to use the Arcade Salesforce toolkit). - Optionally enter a Description.
- Enter your Client ID and Client Secret from your Salesforce app.
Configure the auth endpoints
Replace salesforce-org-subdomain
with your Salesforce Org Subdomain.
- Enter the auth endpoints:
- Authorization Endpoint:
https://salesforce-org-subdomain.my.salesforce.com/services/oauth2/authorize
- Token Endpoint:
https://salesforce-org-subdomain.my.salesforce.com/services/oauth2/token
- Authorization Endpoint:
- Under Refresh Token Settings:
- Enter the Refresh Token Endpoint:
https://salesforce-org-subdomain.my.salesforce.com/services/oauth2/token
- In Response Content Type, select
application/json
.
- Enter the Refresh Token Endpoint:
- Under Token Introspection Settings:
- Check the Enable Token Introspection option.
- Enter the Token Introspection Endpoint:
https://salesforce-org-subdomain.my.salesforce.com/services/oauth2/introspect
- In HTTP Method, select
POST
- In Authentication Method, select
Client Secret Basic
- In Request Content Type, select
application/x-www-form-urlencoded
. - Under Request Parameters section, add the following key-value pair:
- Key:
token
- Value:
{{access_token}}
- Key:
- In Response Content Type, select
application/json
. - In Expiration Format, select
Absolute Unix Timestamp
. - Under the Response Map section:
- Set the expires_in field to
$.exp
- Set the scope field to
$.scope
- Leave the other fields as default
- Set the expires_in field to
- Under Triggers section, enable the On Token Grant and On Token Refresh options.
Optional Auth Settings
- Under PKCE Settings, check the Enable PKCE option if you have enabled PKCE when creating your Salesforce app.
- Leave the Authorization Settings and Token Settings sections as default.
Create the provider
Click the Create button and the provider will be ready to be used in the Arcade Engine.
Using the Arcade Salesforce Toolkit
The Arcade Salesforce toolkit provides tools to interact with various Salesforce objects, such as accounts, contacts, leads, opportunities, notes, tasks, email messages, call logs, etc.
Refer to the toolkit documentation and examples to learn how to use the toolkit to build agents and AI apps that interact with Salesforce services.
Check our introductory documentation to understand what are tools and how tool calling works.
Calling Salesforce APIs directly
Use the Salesforce auth provider to get a user authorization token and call Salesforce API endpoints directly, without the use of any tools. See How Arcade helps with Agent Authorization to understand how this works.
Prerequisites
- Create an Arcade account
- Get an Arcade API key.
- Set the
ARCADE_API_KEY
environment variable withexport ARCADE_API_KEY=<your-api-key>
. - Make sure to have Python 3.10+ or Node.js 18+ installed.
Install the Arcade Python Client
pip install arcadepy
Import necessary modules and instantiate the client
Create a new script called salesforce_example.py
. Import the necessary modules and instantiate the Arcade client:
The Arcade Engine service is available at http://localhost:9099
by default. Replace the host and port, if necessary, to match your environment.
import requests
from arcadepy import Arcade
client = Arcade(base_url="http://localhost:9099") # Automatically finds the `ARCADE_API_KEY` env variable
Set the values required for the Salesforce API call
salesforce_provider_id = "salesforce"
salesforce_org_subdomain = "salesforce-org-subdomain"
user_id = "user@example.com"
scopes = ["read_account"]
Here’s a break down of each value:
salesforce_provider_id
: the ID you entered when setting up the Salesforce auth provider;salesforce_org_subdomain
: your Salesforce Org Subdomain;user_id
: an internal identifier for your application user (it could be an email address, a username, UUID, etc); for demonstration purposes, in this example, enter your own email address;scopes
: the list of scopes you want to request from the user; if you assigned the custom scopes required by the Arcade Salesforce toolkit use["read_account"]
in this example.
Start the authorization process and wait for completion
The Arcade client will prompt the user to access a URL and authorize the app to access their Salesforce data. At the end of the auth process, you will have a token that can be used to call Salesforce APIs on behalf of that user.
auth_response = client.auth.start(
user_id=user_id,
provider=salesforce_provider_id,
scopes=scopes,
)
if auth_response.status != "completed":
print("Please complete the authorization challenge in your browser:")
print(auth_response.url)
# Wait for the authorization to complete
auth_response = client.auth.wait_for_completion(auth_response)
token = auth_response.context.token
if not token:
raise ValueError("No token found in auth response")
If the same scopes have already been authorized by the user before and the token is still valid, the auth process will be skipped and the token will be returned immediately, without prompting with the authorization URL. The Arcade Engine associates a previously authorized token with the user_id
you provided.
Call the Salesforce API
We will now call the Salesforce /parameterizedSearch
API endpoint to search and retrieve account data.
Replace the q
value of "acme"
with any keyword combination of your choice. In a real-world scenario, this value would most likely come from a user’s input. Observe that the q
argument must be a string with two or more characters.
response = requests.post(
f"https://{salesforce_org_subdomain}.my.salesforce.com/services/data/v63.0/parameterizedSearch",
headers={"Authorization": f"Bearer {token}"},
json={
"q": "acme",
"sobjects": [
{"name": "Account", "fields": ["Id", "Name", "Website", "Phone"]},
],
"in": "ALL",
"overallLimit": 10,
"offset": 0,
},
)
if not response.ok:
raise ValueError(
f"Failed to retrieve Salesforce data: {response.status_code} - {response.text}"
)
Create your own Salesforce Tools
If the pre-built tools in the Arcade Salesforce toolkit don’t meet your needs, you can create your own custom tools that interact with the Salesforce APIs.
The code implemented in the Arcade Salesforce tools is the best guide for you to understand how to implement your own. Check the Contact and Account tools in our public Github repository.