Skip to main content

Salesforce

Overview​

The Salesforce integration (salesforce) uses delegated OAuth. IT registers one OAuth app in Salesforce (an External Client App, or an existing Connected App) and sets the most an app may ask for. Each person connects their own Salesforce account once, the first time an app needs it. Calls then run with their token, so they see exactly what Salesforce shows them and nothing more.

Integrationsalesforce
Connection modeDelegated OAuth
IdentityThe signed-in user
Default sensitivityHigh
Availability

Salesforce is part of the local development stack, backed by a Salesforce stand-in with per-user visibility. Testing against a real Salesforce org (Developer Edition) is planned. A fixed OAuth redirect host for real Connected Apps is not built yet: today each app host has its own callback URL.

Prerequisites​

  • A Salesforce org and a Salesforce administrator who can create an External Client App.
  • An Org Admin in vastframe to configure the integration.
  • Optionally, a Salesforce Admins group in your directory to approve requests.

Permissions​

OAuth scopes requested from Salesforce​

Salesforce scopeWhy
apiCall the REST API as the user
refresh_tokenKeep the connection without asking the user to sign in again

vastframe scopes​

Scopes are Salesforce objects with read or write.

ScopeAllows
Account:readSOQL reads of Account, including Account.* relationship fields
Case:readSOQL reads of Case
Case:writeCreate, update and delete Case records
Opportunity:readSOQL reads of Opportunity
Contact:readSOQL reads of Contact
User:readSOQL reads of User

These are the default max scopes. A query reads every object it names, including objects reached through relationship fields, so SELECT Subject, Account.Name FROM Case needs both Case:read and Account:read.

Allowed API calls​

CallMethodScopes
/query?q=<SOQL>GET<Object>:read for each object read
/sobjects/<Object>[/<id>]GET, HEAD<Object>:read
/sobjects/<Object>[/<id>]POST, PATCH, DELETE<Object>:write

Only plain SELECT … FROM <Object> queries pass; sub-queries are refused. Every other path is refused. The gateway adds the API version (v62.0) if your path omits it.

Setup steps​

Step 1: Create an External Client App in Salesforce​

Since the Spring '26 release, Salesforce no longer lets most orgs create new Connected Apps; create an External Client App instead. An existing Connected App with the same settings also works.

  1. In Salesforce Setup, open External Client App Manager and create a new External Client App (distribution state Local).
  2. Turn on OAuth and add the scopes Manage user data via APIs (api) and Perform requests at any time (refresh_token, offline_access).
  3. Require PKCE (vastframe uses the authorization code flow with PKCE).
  4. Set the callback URL to https://<app>.<your-domain>/_tc/int/salesforce/callback for each app that will connect.
  5. Save, and copy the consumer key and secret. Check the app's policies so the people who will connect are allowed to use it.

Step 2: Configure the integration in vastframe​

  1. Open Admin › Integrations and select Salesforce.
  2. Enter the Salesforce app's consumer key (client id) and secret. The secret is encrypted and shown masked afterwards.
  3. Set the authorize, token and API base URLs for your org.
  4. Set Approvers (for example your Salesforce Admins group), Max scopes and Data sensitivity.
  5. Save.

Step 3: Review policies​

The built-in rule "Salesforce read for Sales: auto" approves read-only Salesforce access for people in the Sales department. Everyone else's requests go to the approvers. Adjust it in Admin › Policies.

Use it in an app​

const { records } = await tc.int.salesforce.get('/query', {
q: 'SELECT Id, Subject, Account.Name FROM Case WHERE IsEscalated = true',
});
await tc.int.salesforce.patch(`/sobjects/Case/${id}`, { Status: 'Working' });

The first call for a person who hasn't connected yet fails with CONNECT_REQUIRED. In the browser, call tc.int.salesforce.connect() to send them through Salesforce's consent screen and back. tc.int.salesforce.status() tells you whether they're connected.

Verify​

  1. Open the project's Integrations page and check Grants in effect shows salesforce with the expected scopes.
  2. Open the app and select Connect Salesforce. After consent you return to the app.
  3. Sign in as two people with different Salesforce visibility. Each should see only their own records.
  4. Check Recent calls for the SOQL operations.

People can see and remove their connections under Your connections on a project's Integrations page.

Troubleshooting​

SymptomCauseFix
ACCESS_PENDING #NThe request is waitingAsk the approvers named in the error.
CONNECT_REQUIREDThe person hasn't connected SalesforceCall tc.int.salesforce.connect() from the browser.
ACCESS_DENIED … approved narrowerAn approver approved read-only or fewer objectsWork within the approval, or request again with a clear purpose.
TC_SOQL_NOT_ALLOWEDSub-query or not a SELECTSplit into plain SELECT … FROM queries.
… outside what IT allowsScope not in max scopesAsk IT to widen max scopes, or don't request it.
"That connection attempt expired"Consent took more than 15 minutesStart again.
INTEGRATION_DISABLEDIT turned the integration offContact IT.
Was this page helpful?