docs(salesforce): add Integration User license permission set guidance and Report API error FAQ

[george-dilthey]

What changed

Added two troubleshooting entries to docs/salesforce-integration-faqs.md:

1. A fourth bullet in "Why is a Salesforce object (such as Account) not appearing in Clay?" explaining that Salesforce Integration User license holders must use a permission set with License: Salesforce API Integration — a standard Salesforce-licensed permission set will appear to apply but its object permissions silently do not take effect for this license type.
2. A new FAQ — "Why does Clay show 'The connected Salesforce user's profile doesn't have access to the Report object via the API'?" — covering the exact error Clay surfaces when the integration user lacks Report API access, with steps to grant the needed permissions.

Why

Intercom conversation #215475620340031 (Stephanie Shaw, CanSource): Customer connected Salesforce via Client Credentials using a Salesforce Integration User license. The Salesforce Object dropdown showed only metadata/system objects — Account, Contact, Lead were missing. Customer also saw the error "The connected Salesforce user's profile doesn't have access to the Report object via the API" when trying to use the report source. She had already assigned a permission set but it had no effect. Support agent Bo (bo.morin@clay.com) diagnosed: the permission set used the default Salesforce license, which silently fails for Salesforce Integration User license holders — the correct license for the permission set is Salesforce API Integration. Customer also explicitly noted the docs at the Salesforce integration overview were not robust enough.

Source link(s)

• Intercom conversation: https://app.intercom.com/a/inbox/w28k1kwz/inbox/conversation/215475620340031
• Verifier verdict (Client Credentials flow): PASS — public-actions/authtypes/data/salesforce.json:136-173, auth type salesforce-client-credentials confirmed, unflagged (no feature gate)
• Verifier verdict (metadata-only dropdown when permissions missing): PASS — public-actions/apps/salesforce-new-ui/actions/salesforce-records-view-source-shared/input-parameter-schema.ts:35-44, Clay passes Salesforce's full object list through with no filtering; if standard objects are absent, the authenticated user lacks access in Salesforce
• Verifier verdict (Report API error message text): PASS — public-actions/apps/salesforce-new-ui/actions/salesforce-report-source/input-parameter-schema.ts:63-75, exact error message confirmed, fires on INVALID_TYPE / sObject type 'Report' is not supported
• Verifier verdict (Salesforce API Integration PSL requirement): UNKNOWN — this is a Salesforce platform behavior; Clay's code has no logic that validates license types or permission set license types. Confirmed by support agent Bo's diagnosis.
• Verifier verdict (specific Salesforce permission names "Run Reports" / "View Reports in Public Folders"): UNKNOWN — Clay's code confirms the error and its trigger condition but does not name the specific Salesforce system permissions needed to fix it.
• Screenshots in Intercom conversation part fix: correct malformed markdown for crm.objects.deals.write scope #19 show the exact Report API error message in Clay's UI

Uncertainties

• Salesforce API Integration permission set license requirement (verifier: UNKNOWN): The claim that Salesforce Integration User license holders must use a Salesforce API Integration permission set license is enforced entirely by Salesforce's platform — not by Clay's code. Confirmed by support agent Bo's diagnosis and consistent with Salesforce's documentation. Documented as Salesforce admin guidance rather than Clay-verified behavior.
• "Run Reports" and "View Reports in Public Folders" permission names (verifier: UNKNOWN): Clay's code confirms the exact error message and its trigger, but the specific Salesforce system permission names needed to resolve it are Salesforce platform knowledge not present in Clay's codebase.

Related observations

• PRs docs(salesforce): add FAQ for why Map fields starts empty in Update/Create Record #2241, docs(salesforce): add FAQs for DUPLICATES_DETECTED on Update Record and entity-deleted after merge #2268, docs(salesforce-faqs): document Lead→Contact and Account ID causes of DUPLICATE_VALUE on CampaignMember #2304, docs(salesforce): add managed package AppExchange and Flow automation FAQs #2329, docs(salesforce-faqs): clarify CreatedBy is immutable and reconnect only fixes future records #2344 are all open on docs/salesforce-integration-faqs.md — none overlap with the Integration User license permission set guidance or the Report API access error FAQ added here; reviewed each diff before opening this PR.
• creating-a-restricted-salesforce-user.md has a permission set creation step that specifies License: Salesforce — correct for standard users but could mislead Integration User license holders who follow that doc. A future update could add a callout there. Left out of this PR to keep scope tight.

Closes DOC-2133

[linear-code]

DOC-2133