docs(salesforce-faqs): clarify CreatedBy is immutable and reconnect only fixes future records

[george-dilthey]

What changed

Added two clarifications to the "Why do records created or updated by Clay show my name (or another user's name) in Salesforce's Created By or Last Modified By field?" FAQ in docs/salesforce-integration-faqs.md:

1. Explicitly states that CreatedBy is immutable in Salesforce — set at record creation and cannot be changed afterward by any tool. The previous wording said "Clay does not have a mechanism to override this," which incorrectly framed this as a Clay design choice rather than a fundamental Salesforce database constraint.
2. Clarifies that reconnecting the integration only affects future records — CreatedBy on existing records cannot be retroactively updated.
3. Adds a sentence connecting the admin-permission concern (connected user has excessive Salesforce admin access) to the existing restricted-user guidance, so customers understand that reconnecting under a dedicated integration user solves both the audit-trail issue and the access-scope issue at once.

Why

Intercom conversation #215475657045862 (https://app.intercom.com/a/apps/w28k1kwz/inbox/inbox/conversation/215475657045862): An enterprise customer asked why all Salesforce records created by Clay showed a specific person (Chris Wade) as CreatedBy and Lead Owner, and whether Clay was running through that person's account as a service account. A human support rep had to answer because the existing docs didn't make clear that:

• CreatedBy is a Salesforce-immutable field (a Salesforce constraint, not a Clay limitation)
• Reconnecting only helps for future records — existing CreatedBy fields cannot be changed
• The recommended fix for admin-permission concerns is to reconnect under a restricted integration user

The human's answer: "Clay's Salesforce integration authenticates through the OAuth connection of whoever connected it, so every record Clay creates shows that user as CreatedBy. CreatedBy can't be changed after the fact, it's set by Salesforce at creation. The owner is controllable though: map the Lead Owner field in your Salesforce action to the Salesforce user ID you want. For the admin-level concern, reconnect the Salesforce integration under a dedicated integration user with only the permissions Clay needs."

The Lead Owner coverage was already complete in the existing FAQ ("Why is the owner on a new Salesforce lead or contact set to the Clay integration user?"). Only the CreatedBy immutability and "future records only" scope were missing.

Source link(s)

• Intercom conversation: https://app.intercom.com/a/apps/w28k1kwz/inbox/inbox/conversation/215475657045862
• Slack thread (same conversation, #ent-sysdig-clay): https://clay-hq.slack.com/archives/C0AE3PSG3AS/p1787765474417849?thread_ts=1787765474.417849&cid=C0AE3PSG3AS
• Verifier PASS: CreatedBy set from OAuth access token — /workspace/public-actions/apps/salesforce-new-ui/actions/auth-utils.ts:29-35, /workspace/public-actions/apps/salesforce-new-ui/actions/create-object/action-code.ts:97
• Verifier PASS: OwnerId is a createable field exposed for mapping — /workspace/public-actions/apps/salesforce-new-ui/actions/create-object/input-parameter-schema.ts:124-126
• Verifier PASS: Reconnecting replaces stored OAuth token — /workspace/public-actions/authtypes/data/salesforce.json:68-133

Uncertainties

None. All three behavioral claims verified PASS by the verifier sub-agent with file:line evidence. The CreatedBy immutability is a documented Salesforce API contract.

Related observations

• PRs docs(salesforce): add managed package AppExchange and Flow automation FAQs #2329, docs(salesforce-faqs): document Lead→Contact and Account ID causes of DUPLICATE_VALUE on CampaignMember #2304, docs(salesforce): add FAQs for DUPLICATES_DETECTED on Update Record and entity-deleted after merge #2268, docs(salesforce): add FAQ for why Map fields starts empty in Update/Create Record #2241, docs(salesforce-faqs): document Activity History Bad Request cause and clarify WhoId for leads #2205, and docs(salesforce): add getCellErrorMessagePreview note to DUPLICATES_DETECTED FAQ #2170 are also open on salesforce-integration-faqs.md but cover completely unrelated topics (managed package AppExchange availability, campaign member duplicate handling, Update Record duplicate error, Map fields UX, Activity History queryability, error surfacing via formula). No reconciliation needed with this change.
• The salesforce-integration-overview.md "Testing your connection" section already cross-references which Salesforce user a connection is authenticated as — no changes needed there.

Closes DOC-2099

[linear-code]

DOC-2099