Skip to main content

How to Set up Salesforce

Setup takes about 10 minutes.

Introduction

Connecting Salesforce to Foundational allows Foundational to determine lineage and downstream impact for Salesforce objects and reports.

To make the connection, you need to:

  • Assign Salesforce permissions to Foundational
    ​

  • Choose an authentication method using either a Salesforce user or an external Salesforce application
    ​

  • Connect to Foundational using your Salesforce URL and credentials

Prerequisites

Ensure you have:

  • Salesforce API enabled
    ​

  • A Salesforce user with the API Enabled, Run Reports and View Reports in Public Folders permissions (or explicit sharing of the report folders you want covered). Reports saved in other users' private folders are not read.

  • Salesforce admin access if you plan to create an external Salesforce application
    ​

  • Added Foundational IP addresses to the allowlist, see the article Allowing IP access to Foundational.

Access permissions

The permissions you assign enable Foundational to:

  • Read Salesforce object metadata
    ​

  • Access report definitions
    ​

  • Extract lineage and relationships between Salesforce objects and reports

Salesforce authentication methods

Foundational supports three ways to authenticate with Salesforce. Use the first one unless your org can't support it.

  1. External Client App (Client Credentials Flow) (Recommended): a Salesforce admin creates an External Client App and sets the user it runs as. Foundational connects with the app's Consumer Key and Secret, so no user password is involved and it works with SSO. See Option 1.

  2. External Client App (Refresh Token): the same kind of app, for orgs that can't assign a Run As user. You issue a refresh token once with the Salesforce CLI; Foundational refreshes it automatically from then on. See Option 2.

  3. User and password (legacy): a Salesforce user's username, password and security token. Salesforce is phasing this login out (disabled on orgs created in Winter '26 or later, retired in Summer '27), so use it only if you already rely on it. See Option 3.

Option 1: Authenticate with an External Client App (Recommended)


​Step 1: Create and configure the OAuth app

  1. In Salesforce, click the Gear icon and select Setup.
    ​

  2. In Salesforce Setup, go to Apps → External Client Apps → External Client App Manager and click New External Client App. When you tick Enable Client Credentials Flow under Flow Enablement, Salesforce opens a Confirm Enablement of the Client Credential Flow dialog — click OK.

    Enter these details:
    ​

    • External Client App Name: Foundational
      ​

    • API Name: Foundational
      ​

    • Contact Email: Your email or the app owner’s email
      ​

  3. Under API (Enable OAuth Settings), enable the Enable OAuth checkbox.
    ​

  4. In App Settings, set Callback URL to: https://app.foundational.io.
    ​

  5. Select these OAuth scopes:
    ​


    Add to the right pane:
    ​

    • Manage user data via APIs (api)
      ​

    • Access identity URL service (id, profile, email)
      ​

    • Perform requests at any time (refresh_token)
      ​

    • Access Lightning applications (lightning).
      ​

  6. In Flow Enablement, enable the Client Credentials Flow checkbox.
    ​

  7. Click Create.

Step 2: Configure policies and credentials

  1. Still in Salesforce, go to External Client App Manager and select the app you just created.

  2. In Policies, select Edit.
    ​

  3. The OAuth Policies screen opens.
    ​

    • Enable Client Credentials Flow: Enable the checkbox.
      ​

    • Run As (Username): Enter the username that the Foundational app will run as. The user must have the API Enabled, Run Reports and View Reports in Public Folders permissions. A user on the free Salesforce Integration (API-only) license with a permission set granting these is a good choice. Run As (Username) is a free-text field (not a lookup) that appears only after you tick Enable Client Credentials Flow under Policies → Edit → OAuth Policies → OAuth Flows and External Client App Enhancements; the flow must also be on under Settings → API (Enable OAuth Settings) → Flow Enablement → Enable Client Credentials Flow.

  4. (Optional for the Client Credentials Flow) In App Authorization, set the refresh token validity. The Client Credentials Flow issues no refresh token, so the setting isn't used by it. It does matter for the refresh-token method (Option 2): the Refresh Token Policy under Policies → App Authorization decides how long the token you paste stays valid, so set it to Refresh token is valid until revoked or a long expiry.

  5. Save the changes.
    ​

  6. In the app, select the Settings tab.
    ​

  7. In OAuth Settings, click Consumer Key and Secret. Copy the Consumer Key and the Consumer Secret and store them safely. You’ll need them to set up the connection.

    ​

Step 3: Connect Foundational to Salesforce

  1. In Foundational, open the Connectors & Integrations page.
    ​

  2. In CRM & ERP, select the Salesforce card, and click Connect.
    ​

  3. Click Add Account.
    ​

    ​

  4. The initial setup screen opens. Click Start Setup.
    ​

  5. The Set Up New Connection screen opens.​
    ​

    Enter the details:
    ​

    • If you fix Baz comments that are medium+ use TDD to fix those

    • Authentication Method: External Client App (Client Credentials Flow).

    • Consumer Key (also called Client ID): from your External Client App — open the app, then Settings tab → OAuth Settings → App Settings → button Consumer Key and Secret (Salesforce emails you a verification code first).

    • Consumer Secret (also called Client Secret): same place as the Consumer Key.

  6. Click Next.
    ​

  7. The final setup screen opens. Click Save to complete the connection. Foundational tests the connection when you click Save; if the test fails, the message under the button says what to fix (see Troubleshooting below).

Option 2: Authenticate with an External Client App and a refresh token

Use this method when your org can't set a Run As user for the Client Credentials Flow.

  1. In Salesforce Setup, go to Apps → External Client Apps → External Client App Manager and click New External Client App. Under API (Enable OAuth Settings) tick Enable OAuth, set the Callback URL to http://localhost:1717/OauthRedirect (this is the address the Salesforce CLI listens on, on your own machine, during the one-time login in step 3; Foundational never uses it), and select the scopes Manage user data via APIs (api), Manage user data via Web browsers (web) and Perform requests at any time (refresh_token, offline_access).

  2. Open the app's Policies → Edit → App Authorization and set the Refresh Token Policy to Refresh token is valid until revoked, or to a long expiry. This decides how long the token you paste stays valid.

  3. Issue the refresh token once with the Salesforce CLI. The second command prints an SFDX auth URL of the form force://<clientId>:<clientSecret>:<refreshToken>@<instanceUrl> — the refresh token is its third colon-separated segment, between the Consumer Secret and the @.

    sf org login web --client-id <Consumer Key> --instance-url https://<your-domain>.my.salesforce.com sf org auth show-sfdx-auth-url --target-org <alias> --json

  4. In Foundational, set Authentication Method to External Client App (Refresh Token) and paste the Consumer Key, Consumer Secret and Refresh Token. The Refresh Token field is write-only — it is never shown back to you.

  5. Click Save to complete the connection.

Foundational refreshes the access token automatically at every scan. If Refresh Token Rotation is enabled on the app in Salesforce, Foundational also stores each rotated refresh token automatically, so nothing needs to be done on your side after the setup.

Option 3: Authenticate with user credentials (legacy)


Step 1: Create or use an existing user

  1. Create a new Salesforce user for Foundational or select an existing user.
    ​

  2. Ensure the user has:
    ​

    • Salesforce API access
      ​

    • Run Reports permission
      ​

    • Access to the objects and reports you want Foundational to ingest
      ​

  3. Locate the user’s Salesforce security token.
    You need the security token to set up the connection with Foundational. However, you cannot view a security token, so if you don’t have it, you need to reset it. Check out the Salesforce documentation Reset Your Security Token.

Step 2: Connect Foundational to Salesforce

  1. In Foundational, open the Connectors & Integrations page.
    ​

  2. In CRM & ERP, select the Salesforce card, and click Connect.​
    ​

  3. Click Add Account.
    ​

  4. The initial setup screen opens. Click Start Setup.
    ​

  5. The Set Up New Connection screen opens.
    ​


    Enter the details:
    ​

    • Salesforce URL: Your Salesforce My Domain URL, e.g. https://company.my.salesforce.com. You can find it in Salesforce Setup → Settings → Company Settings → My Domain, in the My Domain Details section, field Current My Domain URL. Pasting the Lightning URL (https://company.lightning.force.com) or the Setup URL (https://company.my.salesforce-setup.com/...) also works. For a sandbox, use the sandbox's own My Domain URL, e.g. https://company--uat.sandbox.my.salesforce.com.

    • Authentication Method: User and password (legacy).

    • User Name: The username that you want Foundational to use to access Salesforce. This user must have API access enabled.
      ​

    • Password: The user’s password.
      ​

    • User Token: The value you saved earlier.
      ​

  6. Click Next.
    ​

  7. The final setup screen opens. Click Save to complete the connection. Foundational tests the connection when you click Save; if the test fails, the message under the button says what to fix (see Troubleshooting below).

Troubleshooting

These are the messages Foundational shows under the Save button when the connection test fails.

"Could not reach … Check the Salesforce URL"

The host in the URL doesn't exist or isn't reachable. Use the My Domain URL from Setup → My Domain, not an instance URL such as na123.salesforce.com, a Visualforce or Experience Cloud URL, or (for sandboxes) a URL without the .sandbox part. If the URL is right, make sure your network allows Foundational's IP addresses.

"The Client Credentials Flow isn't fully enabled for this external client app"

Salesforce error: invalid_grant: no client credentials user enabled. The flow has to be enabled in two places on the External Client App: Settings → API (Enable OAuth Settings) → Flow Enablement → Enable Client Credentials Flow, and Policies → Edit → OAuth Policies → OAuth Flows and External Client App Enhancements → Enable Client Credentials Flow, where you also fill in Run As (Username). Ticking the flow on the app creation form does not pre-tick the one under Policies, and enabling it in only one of the two places produces this same error. Turning the Settings-side switch off also clears the Policies-side checkbox and Run As (Username), and re-enabling it on Settings does not restore them, so after any change under Settings go back to Policies → Edit and set both again. Save both, then click Save in Foundational again.

"The Consumer Key is incorrect" / "The Consumer Secret is incorrect"

Copy both again from External Client App Manager → your app → Settings tab → OAuth Settings → App Settings, button Consumer Key and Secret (it opens a new tab and asks for an identity-verification code that Salesforce emails you). A legacy Connected App shows the field Consumer Key and Secret with a Manage Consumer Details button instead.

"Salesforce rejected the username, password or security token"

Check all three. Resetting the password also regenerates the security token, so update the connector after any reset. A sandbox user must be used with the sandbox's URL. If Foundational's IP addresses are not in the org's trusted IP ranges, the security token is mandatory.

"This org restricts password logins through the SOAP login() API"

Salesforce disables this login on orgs created in Winter '26 or later and is retiring it. Switch the connector to External Client App authentication (Option 1, or Option 2 if the org can't assign a Run As user).

"Missing access to Salesforce reports"

The user Foundational runs as needs API Enabled, Run Reports and View Reports in Public Folders, or explicit sharing of the report folders. A report is ingested only if that user can run it: the folder must be shared with them at Viewer or better, and they need access to the report type's underlying objects and fields. View All Data on its own is not sufficient. Reports the user can't run are skipped; reports in other users' private folders are never read.

"The Salesforce authorization has expired or was revoked"

The refresh token was revoked, expired under the app's Refresh Token Policy, or the External Client App was changed. Re-run the CLI login (sf org login web --client-id ... --instance-url ...), then run sf org auth show-sfdx-auth-url --target-org <alias> --json and take the refresh token from the returned force://<clientId>:<clientSecret>:<refreshToken>@<instanceUrl> URL (its third colon-separated segment), and paste it into the connector's Refresh Token field. Applies to the refresh-token method (Option 2) only.

Related Articles
Did this answer your question?