Guides

Connect Salesforce

Bigeye connects to Salesforce via a Salesforce External App authenticated with the OAuth Client Credentials flow. The connection is read-only, so Bigeye can query your Salesforce objects to compute metrics but cannot modify any data.

This guide covers:

  1. Create a dedicated Salesforce service account (integration user).
  2. Grant object read access to the service account via a permission set.
  3. Create a Connected App in Salesforce (with the Client Credentials flow enabled).
  4. Configure the app's policies — pre-authorize the service account and set it as the Run As user.
  5. Gather connection details from Salesforce.
  6. Add Salesforce as a data source in Bigeye.

1. Create the Salesforce Service Account

  1. Log into Salesforce as an administrator. Click the Gear icon in the top right and select Setup. In the Quick Find box, type Users and click Users.

  1. Click New User.

  2. Enter a clear name, e.g. Bigeye Service Account, and provide a valid corporate email address you can access (Salesforce sends an activation email to it).

  3. Set User License to Salesforce Integration.

  4. Set Profile to Salesforce API Only System Integrations.

  5. Ensure Active is checked, then click Save.

2. Grant Object Access via a Permission Set

The service account's profile grants API access but no data access. Grant read access to the objects Bigeye should monitor using a permission set.

  1. In Setup, search for Permission Sets in the Quick Find box and open it.

  2. Click New to create a custom permission set, e.g. Bigeye Read Access.

  3. Set the License to Salesforce API Integration

  4. Open the permission set, go to Object Settings, and grant Read access to each Salesforce object you want Bigeye to monitor (e.g. Accounts, Contacts, Leads).

  5. Click Manage Assignments → Add Assignment and select the service account user you created in step 1.


3. Create a Connected App in Salesforce

  1. In Setup, under Platform Tools, select Apps → App Manager and click New External Client App.

  1. Fill out the Basic Information section:

    • Connected App Name: e.g. Bigeye
    • API Name: auto-populates
    • Contact Email: your contact email

  2. Under API (Enable OAuth Settings), check Enable OAuth Settings and configure:

    • Callback URL: http://localhost:1717/OauthRedirect

    • Selected OAuth Scopes: at minimum add

      • Manage user data via APIs (api)
      • Perform requests at any time (refresh_token, offline_access)

    • Flow Enablement: Check Enable Client Credentials Flow

    • Security: Leave Require Secret for Web Server Flow and Require Secret for Refresh Token Flow checked.


  1. Click Create. Salesforce will note that changes may take up to 10 minutes to propagate.

4. Configure App Policies and Run As User

Enabling the Client Credentials Flow (step 3) is only half the configuration — Salesforce also needs to know which user the flow runs as and that the app is authorized for that user. This ties the app to the service account from steps 1–2.

  1. From Setup → Apps → External Client Apps → External Client App Manager, find your Connected App and click the dropdown → Edit Policies.

  2. Under App Policies → Available Permission Sets, select the permission set you created in step 2 (e.g. Bigeye Read Access) and move it to Selected Permission Sets. This authorizes the service account to use the app.

  3. Under OAuth Policies, set Permitted Users to Admin approved users are pre-authorized.

  4. Under OAuth Policies → Client Credentials Flow, set Run As to the service account user from step 1 (the Username you configured).

  1. Click Save.

5. Gather Connection Details from Salesforce

You'll need three values for the Bigeye source configuration.

Instance URL (LoginURL)

Your Salesforce instance URL — what you see in the browser when you're logged in. Example: https://yourcompany.my.salesforce.com.

To confirm: Setup → Company Settings → My Domain shows the current My Domain URL.

Consumer Key and Consumer Secret

  1. Setup → Apps → External Client Apps → External Client App Manager, find your Connected App, click the dropdown → Edit Settings.
  2. Under OAuth Settings, click Consumer Key and Secret
  3. Copy the Consumer Key and Consumer Secret. Treat the Consumer Secret like a password.

6. Add Salesforce as a Data Source in Bigeye

In Bigeye:

  1. Go to Catalog → Sources → Add Source and select Salesforce.

  2. Fill out the configuration:

FieldValue
NameA display name for this source.
HostThe instance URL from step 4 (e.g. https://yourcompany.my.salesforce.com).
Consumer KeyThe Consumer Key from the Connected App.
Consumer SecretThe Consumer Secret from the Connected App.
  1. Click Validate source to validate the connection.

Known Limitations

  • Percentile and median metrics are not supported. The underlying SQL engine does not provide a working WITHIN GROUP or percentile_cont substitute. These metrics are hidden from the metric picker on Salesforce sources.
  • Indexing time. Salesforce orgs typically expose hundreds of standard and custom objects, and Bigeye indexes columns per-object. The first full index of a Salesforce source can take ~10 minutes; subsequent re-indexes are faster.

Troubleshooting

❗

no client credentials user enabled

The Connected App doesn't have a Run As user set. Return to step 2.3 and select an integration user under OAuth Policies → Client Credentials Flow.

❗

invalid_client_id / invalid_client_secret

Re-copy the Consumer Key and Consumer Secret from Manage Consumer Details. Salesforce displays the Consumer Secret only after verification — don't trust a previously copied value if it's been more than a session.

Next Steps