Salesforce

The Salesforce auth provider enables tools and agents to call Salesforce APIs on behalf of a user.

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 MCP Server, 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

For this guide, we’ll create an External Client App. Make sure to follow the instructions below while you create your External Client App .

When creating your app, make sure to:

• Under “API (Enable OAuth Settings)”, check the Enable OAuth option
• Set the callback URL to the redirect URL generated by Arcade (see below) or set any temporary URL for now, you can change it later.
• In the OAuth Scopes section, add the two following scopes:
  • “Manage User Data Via APIs (api)”
  • “Perform requests at any time (refresh_token, offline_access)”
• Check “Enable Token Exchange Flow” and keep the “Require secret for Token Exchange Flow” also checked.
• 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 “Settings” tab, under “OAuth Settings”, click the “Consumer Key and Secret” button. It will open a page showing the Consumer Key and Consumer Secret values. Take note of these values, you will need them to configure Salesforce Auth Provider in Arcade.

Go back to the App’s page and click the Policies tab and follow the instructions below:

• Under “OAuth Settings”, select the custom OAuth scopes listed in the Create and Assign Custom Scopes to your External Client App section.
• In the “App Authorization” area:
  • Under “Refresh Token Policy”, check the option “Refresh token is valid until revoked”.
  • In “IP Relaxation”, select Relax IP Restrictions.
• Click the “Save” button to save your changes.

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:

1. In the Setup menu, click on Quick Find in the top left corner and type "my domain".
2. In the search results, under Company Settings, click on My Domain.
3. 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 Secret

Set the SALESFORCE_ORG_SUBDOMAIN secret in the Arcade Dashboard:

• Click on the “Secrets” section in the Arcade Dashboard left-side menu.
• Click on the “Add Secret” button.
• Enter SALESFORCE_ORG_SUBDOMAIN as the secret ID.
• Enter your Salesforce Org Subdomain as the secret value.
• Click on the “Create” button.

Create and Assign Custom Scopes to your External Client 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 MCP Server are listed below, along with their descriptions:

• 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 an External Client App  Salesforce documentation to understand how to define and assign these scopes to your Salesforce app.

Configuring Salesforce Auth

Using the Arcade Salesforce MCP Server

The Arcade Salesforce MCP Server provides tools to interact with various Salesforce objects, such as accounts, contacts, leads, opportunities, notes, tasks, email messages, call logs, etc.

Refer to the MCP Server documentation and examples to learn how to use the MCP Server to build agents and AI apps that interact with Salesforce services.

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

1. Create an Arcade account
2. Get an Arcade API key.
3. Set the ARCADE_API_KEY environment variable (export ARCADE_API_KEY=<your-api-key> on Bash, $env:ARCADE_API_KEY="<your-api-key>" on PowerShell).
4. Make sure to have Python 3.10+ or Node.js 18+ installed.

pip install arcadepy

import requests
from arcadepy import Arcade
 
client = Arcade(base_url="http://localhost:9099")  # Automatically finds the `ARCADE_API_KEY` env variable

salesforce_provider_id = "salesforce"
salesforce_org_subdomain = "salesforce-org-subdomain"
user_id = "{arcade_user_id}"
scopes = ["read_account"]

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")

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}"
    )

npm install @arcadeai/arcadejs

import { Arcade } from "@arcadeai/arcadejs";
 
const client = new Arcade((baseURL = "http://localhost:9099")); // Automatically finds the `ARCADE_API_KEY` env variable

const salesforceProviderId = "salesforce";
const salesforceOrgSubdomain = "salesforce-org-subdomain";
const userId = "{arcade_user_id}";
const scopes = ["read_account"];

let authResponse = await client.auth.start(userId, {
  provider: salesforceProviderId,
  scopes: scopes,
});
 
if (authResponse.status !== "completed") {
  console.log("Please complete the authorization challenge in your browser:");
  console.log(authResponse.url);
}
 
// Wait for the authorization to complete
authResponse = await client.auth.waitForCompletion(authResponse);
 
if (!authResponse.context.token) {
  throw new Error("No token found in auth response");
}
 
const token = authResponse.context.token;
 
if (!token) {
  throw new Error("No token found in auth response");

// Use the Salesforce API
const response = await fetch(
  `https://${salesforceOrgSubdomain}.my.salesforce.com/services/data/v63.0/parameterizedSearch`,
  {
    headers: {
      Authorization: `Bearer ${token}`,
    },
    method: "POST",
    body: JSON.stringify({
      q: "acme",
      sobjects: [
        { name: "Account", fields: ["Id", "Name", "Website", "Phone"] },
      ],
      in: "ALL",
      overallLimit: 10,
      offset: 0,
    }),
  },
);
 
if (!response.ok) {
  throw new Error(
    `HTTP error! status: ${response.status} - ${await response.text()}`,
  );

Create your own Salesforce Tools

If the pre-built tools in the Arcade Salesforce MCP Server 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.