OrgRelay
orgrelay.com

Salesforce connector: CRM reads for everyone, two small writes behind approval

This page is for the Salesforce admin who will create the app and pick the integration user. It covers the OAuth setup in today's Setup menus, the SOQL each tool runs, how paging and IDs behave, and what an approver checks before a task is added or an opportunity moves stage.

The connector uses the Salesforce REST API at version v62.0. It signs in with the OAuth 2.0 authorization code flow with PKCE and requests the scopes api and refresh_token. Salesforce returns the org's instance_url with the token, and the connector sends every call there. The connector spec shows where a CRM connector fits in OrgRelay.

What staff can ask

  • "Find the account Northwind and show its open deals." This calls customers.search with keyword: Northwind, then customers.get on the account ID.
  • "Which opportunities are in Negotiation and closing this quarter?" This calls customers.deals with stage: Negotiation/Review and open_only: true. The stage name must match the org's picklist value.
  • "Show new cases about invoices." This calls tickets.search with keyword: invoice and status: New.
  • "Is Maria Lopez already a lead?" This calls customers.search with object: Lead.
  • "Add a follow-up task on the Northwind renewal for Friday." This calls customers.add_task with the opportunity ID, a subject and due_date. It waits for approval.

The names come from standard tools. Sales staff who also use the HubSpot connector see the same customers.deals tool there, and support staff find tickets.search on the Zendesk connector too.

Tools

Tool Access What it does Key parameters
customers.search read Accounts, contacts or leads whose Name contains a keyword, most recently modified first keyword, object (Account default, Contact, Lead), limit, cursor
customers.get read One account with up to 20 contacts and up to 20 open opportunities customer_id (Account ID)
customers.deals read Opportunities with stage, amount, close date, account and owner, latest close date first keyword, stage, open_only, limit, cursor
tickets.search read Cases with number, subject, status, priority, origin and account or contact, newest first keyword (subject contains), status, limit, cursor
customers.add_task write · approval Creates a Task with status Not Started on a record record_id, subject (required), due_date, description
customers.update_deal_stage write · approval Sets StageName on one opportunity deal_id, stage

What the code does underneath:

  • Searches are SOQL LIKE queries on Name or Subject. They are not SOSL full-text searches. A keyword matches anywhere in the field. The connector escapes quotes, backslashes, % and _ before building the query.
  • Stage and status filters are exact matches. "Closed Won" works, "won" does not. Ask the assistant to list deals first if you are unsure of the picklist values.
  • Paging follows Salesforce's query cursor. The connector runs the SOQL once and asks for batches of 200 with the Sforce-Query-Options: batchSize=200 header; Salesforce's documentation notes that the batch size it returns is not guaranteed. The OrgRelay cursor records which batch (nextRecordsUrl) and how far into it the last page ended, so paging continues through the whole result set without an OFFSET limit. limit defaults to 20 and caps at 100. Salesforce expires query cursors that sit unused; when that happens the connector asks you to run the search again from the first page. Cursor paging requires OrgRelay 1.4.0 or later.
  • Record IDs must be 15 or 18 alphanumeric characters. Anything else is rejected before a call is made.
  • Amounts carry a currency only in multi-currency orgs. The connector reads CurrencyIsoCode when the field exists; otherwise the currency is left empty.

Credentials and scopes

The connection has two required fields and two advanced ones:

  • Consumer key (the client ID) and consumer secret, from your External Client App.
  • Login URL, advanced. The default is https://login.salesforce.com. For a sandbox, use https://test.salesforce.com or your My Domain URL.
  • Instance URL, advanced. Leave it empty. The connector stores the instance_url returned at authorization.

Scopes: Manage user data via APIs (api) and Perform requests at any time (refresh_token, offline_access). There is no separate read-only scope in Salesforce. What the connector can read or change is decided by the authorizing user's profile, permission sets, field-level security and sharing. That user needs the API Enabled permission. For read-only use, authorize as a user who can read Accounts, Contacts, Leads, Opportunities and Cases but cannot edit them. Also switch the two write tools off in OrgRelay; Salesforce will reject writes either way.

Edition matters. Enterprise, Unlimited, Performance and Developer editions include API access. Professional Edition needs API access added to the contract.

Token lifetime: Salesforce does not return an expiry with the access token. The connector assumes 15 minutes, the shortest session timeout, and uses the refresh token before then. How long the refresh token itself lasts is set in the app's policies (valid until revoked, or expire after a period or after inactivity). If you set an expiry, plan to authorize again when it passes. OrgRelay stores the secret and tokens encrypted and shows only the last four characters; the auth page has the details.

Which actions need approval

Both write tools create an approval request. They run only after the owner or a designated approver accepts. The approver sees the record ID and the values that will be written:

  • customers.add_task: the record ID, subject, due date and description. The connector reads the ID prefix to decide where the task attaches. IDs starting with 003 (Contact) or 00Q (Lead) go into WhoId. Every other ID, such as an Account, Opportunity or Case, goes into WhatId. The task is created with status Not Started and is owned by the authorizing user.
  • customers.update_deal_stage: the opportunity ID and the new stage name. Salesforce applies its own validation rules, required fields and automation, such as flows on stage change. A rejected update comes back with Salesforce's message, and nothing is changed.

Approved calls carry the idempotency key orgrelay-approval-<approval id>. The REST endpoints used here take no idempotency header, so OrgRelay uses the key to run each approval once and does not send it to Salesforce. A rejected or expired approval never reaches the org. See approvals and writes and, for the reasoning, human in the loop.

Set it up

Since Spring '26, Salesforce has turned off creation of new connected apps by default and points new integrations to External Client Apps. An existing connected app with OAuth enabled still works with the same steps from step 4 onwards.

  1. In Setup, enter "External" in Quick Find and open External Client App Manager. Click New External Client App and enter a name (OrgRelay) and a contact email.
  2. Under API (Enable OAuth Settings), enable OAuth. Set the callback URL to the one OrgRelay shows, which is your OrgRelay address followed by /oauth/callback. Add the scopes api and refresh_token, offline_access. Tick Require Proof Key for Code Exchange (PKCE).
  3. Save. Open the app's OAuth settings and click Consumer Key and Secret; Salesforce may send a verification code to your email first. A new app can take several minutes to become usable.
  4. Under the app's policies, decide who may authorize it and how long refresh tokens last.
  5. In OrgRelay, open Admin → Business systems → App directory, pick Salesforce, enter the key and secret (and the Login URL for a sandbox), and click Authorize. Sign in as the integration user and approve.
  6. OrgRelay reads /services/oauth2/userinfo and shows the user's name and the instance host. The connection test later calls the /limits resource.
  7. Grant the connector to sales and support roles. Keep customers.update_deal_stage for roles that own the pipeline.

A free Developer Edition org, or a sandbox of your production org, is a good place to try the write tools first. If you build connectors for other systems, the quickstart and connector check explain the testing OrgRelay expects.

Limits and things it does not do

Salesforce counts API requests per org over a rolling 24 hours. The API limits cheatsheet gives Enterprise Edition a base of 100,000 requests plus 1,000 per Salesforce or Salesforce Platform licence, and caps Developer Edition at 15,000. A search usually costs one request, or two when a page spans two batches. customers.get costs three. OrgRelay adds its own guards: 120 calls per minute per connection by default, and a 60-second pause after three failures in a row. If Salesforce answers 429, OrgRelay waits for Retry-After, or 60 seconds.

The connector does not:

  • create, update or delete accounts, contacts, leads or cases;
  • read custom objects or custom fields (it selects a fixed list of standard fields);
  • run arbitrary SOQL, SOSL or reports;
  • send email, log calls, or touch Chatter, files or quotes.

For anything beyond that, the OpenAPI import can describe an Apex REST endpoint of your own, or you can serve it over the MCP transport. Change notifications can reach OrgRelay through events. Results are cut to about 12,000 characters before the AI reads them.

Official MCP server and OrgRelay

Salesforce offers Hosted MCP Servers, announced as generally available in April 2026. They are managed endpoints under api.salesforce.com/platform/mcp/v1/. Pre-configured SObject servers range from read-only (sobject-reads) to full create, update and delete (sobject-all). They are set up through an External Client App with the mcp_api scope. Salesforce's documentation stresses that every operation stays within the signed-in user's object permissions, field-level security and sharing.

OrgRelay's third-party MCP connection works with servers that accept a token in a request header. Salesforce's hosted servers expect each user to sign in through the External Client App's interactive OAuth flow, and that flow, with PKCE, cannot be completed from an OrgRelay connection. Staff who want the hosted servers can use them from their own MCP clients, while OrgRelay serves the company-wide case through this connector with its own controls: grants per role and department, approval before each write, one audit log across Salesforce and your other systems, and everything running on the company's own machine. The enterprise patterns page compares the two set-ups, and official MCP servers lists other vendors' servers. For the sales team's view, see the sales agent.

Common questions

Whose permissions does OrgRelay use in Salesforce?

The permissions of the user who clicked Authorize. Every query runs as that user, so profile, permission sets, field-level security and sharing rules all apply. Authorize with an integration user whose access matches what you want OrgRelay staff to see, not with a system administrator.

How many API calls does the connector use?

Usually one REST call per tool call. A search page that crosses a 200-row batch boundary takes two, and customers.get makes three in parallel (the account, its contacts and its open opportunities). These count against the org's rolling 24-hour API request allocation, which on Enterprise Edition starts at 100,000 plus an amount per user licence.

Can we connect a sandbox first?

Yes. Create the External Client App in the sandbox, then set the advanced Login URL to https://test.salesforce.com or the sandbox's My Domain URL before you authorize. The instance URL is taken from the token response, so nothing else changes.

Updated (Singapore time) · OrgRelay Team