Connecting a Salesforce Org
Connect your Salesforce org to MeshMesh using one of three OAuth methods
MeshMesh connects to Salesforce using OAuth. You authenticate through your browser — no passwords are stored. There are several ways to connect, depending on your setup:
- Quick Connect — fastest, desktop only, no admin setup.
- External Client App — your own app, works headless (web app, Slack, hosted MCP clients) as well as desktop.
- Custom Connected App — your own app credentials via the Salesforce CLI, desktop only.
- MeshMesh Connected App — a managed package an admin installs once (pre-release).
Quick Connect (Preferred)
The fastest way to connect — just click and go.
No admin setup or package installation required. Your Salesforce user just needs API permissions (enabled by default for most profiles).
Connect from MeshMesh Studio
Open MeshMesh Studio desktop → Connections → select Quick Connect → click Connect.
Authorize in browser
Sign in through the browser and approve access. Done.
Quick Connect uses the Salesforce CLI and is desktop only. To use MeshMesh on the web or from Slack, use the External Client App method below.
External Client App
Use your own Salesforce External Client App — the only method that works headless.
This is the method to choose if you want to use MeshMesh without the desktop app: on the web, from the Slack integration, or with other hosted MCP clients. You create an External Client App (ECA) in your own org and register a MeshMesh callback URL on it. Because MeshMesh stores and refreshes the OAuth token server-side (no Salesforce CLI, no laptop, no desktop app required), the connection keeps working in fully server-side / hosted contexts.
Create an External Client App in Salesforce
In Salesforce Setup, go to External Client App Manager → New External Client App. Then:
-
Enable OAuth Settings (use the defaults for the other fields).
-
OAuth Scopes — add at minimum:
apirefresh_tokenoffline_accessweb
Add any other scopes your use case needs.
Configure security settings
- Require Proof Key for Code Exchange (PKCE): leave enabled.
- Enable Client Credentials Flow: leave this off — MeshMesh uses the authorization-code flow, not client credentials.
- A consumer secret is not required — MeshMesh connects as a public PKCE client.
Set the Callback URL
Set the app's Callback URL to the exact URL shown in the MeshMesh Connections modal for your platform and environment:
| Where you run MeshMesh | Callback URL |
|---|---|
| Web (production) | https://studio.meshmesh.io/auth/sf-callback |
| Web (staging) | https://studio-staging.meshmesh.io/auth/sf-callback |
| Desktop (production) | https://auth.meshmesh.io/sf-callback |
| Desktop (staging) | https://staging-auth.meshmesh.io/sf-callback |
If you use MeshMesh on both web and desktop, register both callback URLs on the app. The Connections modal always shows the exact value(s) to copy for your current context.
Wait for activation
A new External Client App can take up to 30 minutes to become available. If the connection fails right after creation, wait and try again.
Copy the Consumer Key
In the app's Settings → OAuth Settings, copy the Consumer Key. This is a public identifier, not a secret.
Connect from MeshMesh
Open Connections → select External Client App → paste your Consumer Key → pick the environment → click Connect and authorize in the browser.
Pick this method for the web app, Slack, or any hosted client. MeshMesh uses whatever OAuth scopes you configured on your External Client App, so the app itself is the source of truth for access.
Custom Connected App
For orgs that require their own OAuth credentials or specific scopes, on desktop.
Use this method on the desktop app if your org has restrictions on third-party apps or you need fine-grained control over OAuth scopes. It authenticates through the Salesforce CLI, so it does not work on the web or from Slack — use the External Client App method above for those.
Create a Connected App in Salesforce
In Salesforce Setup, go to App Manager → New Connected App. Configure the following:
- Enable OAuth Settings: Check this box
- Callback URL:
http://localhost:1717/OauthRedirect(the Salesforce CLI loopback callback) - OAuth Scopes: Add at minimum:
apirefresh_tokenoffline_accessweb
Add full or other scopes as needed for your use case.
Copy credentials
Save the Consumer Key (Client ID) — and the Consumer Secret if your app requires one — from the connected app settings.
Enter credentials in MeshMesh Studio
Open MeshMesh Studio desktop → Connections → select Custom Connected App → expand OAuth Scopes & Credentials → enter your Client ID (and Client Secret if required).
Connect and authorize
Click Connect, sign in through the browser, and approve access.
Use this method if your org blocks third-party connected apps or if you need fine-grained control over which OAuth scopes are granted, and you connect from the desktop app.
MeshMesh Connected App (Pre-release, Supported Clients Only)
This method is currently in pre-release and only available to supported clients. It may change in future releases.
Best for teams — no setup needed.
The MeshMesh Connected App method uses a managed package that installs an External Client App (ECA) in your Salesforce org. An admin installs it once, then everyone in the org can connect.
Install the MeshMesh Studio package
A Salesforce admin installs the MeshMesh Studio package in the target org. Choose "Install for All Users" when prompted.
Use the URL that matches the org you're installing into — only the host differs, the package id is the same everywhere:
- Production:
https://login.salesforce.com/packaging/installPackage.apexp?p0=04tfj000000GGiLAAW - Sandbox:
https://test.salesforce.com/packaging/installPackage.apexp?p0=04tfj000000GGiLAAW - Custom My Domain:
https://<your-my-domain-host>/packaging/installPackage.apexp?p0=04tfj000000GGiLAAW— substitute your org's My Domain host. Example:https://acme.my.salesforce.com/packaging/installPackage.apexp?p0=04tfj000000GGiLAAW. Sandbox my-domains follow the same pattern, e.g.https://acme--uat.sandbox.my.salesforce.com/packaging/installPackage.apexp?p0=04tfj000000GGiLAAW.
Log into the target org in your browser before opening the install URL. If you're signed into a different org, the package lands there instead.
Enable the External Client App
In Salesforce Setup, go to External Client App Manager, find MeshMesh Studio, and click Enable.
Connect from MeshMesh Studio
Open MeshMesh Studio desktop → Connections → select MeshMesh App as the connection method → click Connect.
Authorize in Salesforce
Sign in through the browser and approve access. You'll be redirected back to MeshMesh Studio.
The package install and enable steps are one-time admin setup. After that, any user in the org can connect without additional configuration.
Sandbox & Custom Domains
MeshMesh supports production orgs, sandbox orgs, and custom domains (My Domain). Two things have to match the org you're connecting to: the package install URL (see the install step above) and the environment picker in the Connections modal.
For sandbox orgs: Select Sandbox in the environment picker before connecting. This directs authentication to test.salesforce.com. Make sure you installed the package via the sandbox install URL — https://test.salesforce.com/packaging/installPackage.apexp?p0=04tfj000000GGiLAAW — not the production one.
For custom domains: Select Custom Domain and enter your instance URL (e.g., https://MyDomain--SandboxName.sandbox.my.salesforce.com). The package install URL needs to use that same host:
https://<your-my-domain-host>/packaging/installPackage.apexp?p0=04tfj000000GGiLAAWIf you install the package in production but pick Sandbox (or vice versa) when connecting, OAuth fails with "grant type not supported" — the auth code was issued by one host and the token endpoint can't redeem it on another.
Troubleshooting
"External client app not installed" — Install the MeshMesh Studio package in your org and enable it in Setup → External Client App Manager. Use the install URL matching your environment:
- Production:
https://login.salesforce.com/packaging/installPackage.apexp?p0=04tfj000000GGiLAAW - Sandbox:
https://test.salesforce.com/packaging/installPackage.apexp?p0=04tfj000000GGiLAAW - Custom My Domain:
https://<your-my-domain-host>/packaging/installPackage.apexp?p0=04tfj000000GGiLAAW
"Grant type not supported" — The package was installed in a different org than the one you're trying to connect to (e.g. installed in production but connecting to a sandbox). Either install the package in the right org using the URL matching your environment above, or change the Environment selector in the Connections modal to match where the package is installed.
"Cross-org OAuth error" — The MeshMesh Studio package must be both installed and enabled in the org you're connecting to. Go to Setup → External Client App Manager → MeshMesh Studio → Enable.
"Authorization failed" — Verify that your External Client App or Connected App has the required OAuth scopes (api, refresh_token, offline_access, web).
"Salesforce CLI required" — Quick Connect and Custom Connected App both use the Salesforce CLI (desktop only). To connect without the CLI — including on the web or from Slack — use the External Client App method instead.
"redirect_uri mismatch" / "invalid redirect URI" (External Client App) — The Callback URL registered on your External Client App must exactly match the one shown in the Connections modal for your platform and environment (web vs desktop, production vs staging). Copy the value from the modal and register it verbatim; if you use both web and desktop, register both.
Connection timeout — Check your network and firewall settings. Ensure your browser can reach login.salesforce.com (or test.salesforce.com for sandboxes).