Salesforce Service Account Requirements

💡

Note: If you're connecting via OAuth with your own System Administrator account, you can skip this guide—your admin credentials already have the necessary access. This document is for organizations that prefer to provision a dedicated service account with specific permissions.

---

Service Account Setup

1. Create the Integration User

Create a dedicated user for the Upside integration (or use an existing service account).

2. Create a Permission Set

Create a Permission Set named something like "Upside Integration" and assign it to the integration user.

3. Grant System Permissions

In the Permission Set's System Permissions, enable:

4. Verify Session Settings

• Go to Setup → Session Settings
• Ensure "Lock sessions to the IP address from which they originated" is unchecked for the integration user
• If Login IP Ranges are configured on the user's profile, ensure Fivetran's IP ranges are allowed (see Fivetran's IP addresses)

5. Grant Object Permissions

Choose one of the two approaches below:

❓

Why View All instead of Read? The Read permission only grants access to records owned by or shared with the user. Upside needs access to all records regardless of ownership. See Salesforce documentation for details.

---

Recommended Approach: View All on All Objects

We strongly recommend granting View All access to all standard and custom objects. This approach:

• Eliminates sync failures from missing object access
• Handles formula fields automatically — formulas often reference objects you wouldn't expect
• Future-proofs your setup — new fields and objects won't break the sync
• Requires no debugging — the most common support issues stem from missing object access

To configure:

• Go to Object Settings in the Permission Set
• For each object, enable View All
• Or, assign a profile with View All access to all objects

---

Alternative Approach: Granular Permissions

If your security policy requires minimum-necessary access, you can grant access only to specific objects. Be aware that this approach may require collaborative iteration with the Upside team if the sync encounters missing permissions.

Object Permissions

Grant View All permission on these objects in Object Settings:

⚠️

Important: You must also grant View All on any objects referenced by formula fields, lookup fields, or roll-up summaries on the objects above. Salesforce validates access to all referenced objects when syncing field metadata, and missing access causes hard-to-debug sync failures. If you're unsure which objects your custom fields reference, consider using the Recommended Approach instead.

Optional objects (grant View All if the feature is enabled in your org):

---

Appendix: Complete List of Objects Upside Consumes

This appendix lists all Salesforce objects that Upside may access, including those that typically don't require explicit permission grants.

Objects with Inherited or Automatic Access

These objects don't appear in Object Settings and don't require separate permission grants:

Tooling API Metadata Objects

These objects are accessed through the Tooling API and don't appear in Object Settings:

⚠️

Important: FieldDefinition queries validate that the user can access all objects referenced by fields (including formula field references and lookup targets). This is the most common cause of sync failures with granular permissions.

What If an Object Isn't in My Org?

If you don't see an object we've listed:

1. It may be a Setup object — Objects like Profile and UserRole are accessed via system permissions, not Object Settings
2. A feature may not be enabled in your instance — Some objects only exist when features are turned on (e.g., Products, Field History Tracking)
3. Check the API name — UI names differ from API names (e.g., "Opportunity Products" = OpportunityLineItem)

---

Troubleshooting

Missing Object Access

If Upside Support contacts you about a sync failure related to missing object permissions, it typically means the service account can't access an object that's referenced by a field on an object being synced.

Why it happens: When syncing field metadata, Salesforce validates that the user can access all objects referenced by those fields—including formula field references, lookup targets, and roll-up summaries.

Example: A formula field on Opportunity references a field from Territory2. Even if you're not syncing Territory data, the service account needs access to Territory2 to read the field metadata.

Resolution options:

1. Grant View All on all objects (recommended) — This eliminates the issue entirely
2. Grant access to the specific object — Upside Support will let you know which object is missing, though identifying it can take some back-and-forth since Salesforce's error messages are intentionally vague for security reasons

Sync Failures After Salesforce Changes

If syncs start failing after changes to your Salesforce org:

• New custom objects — May be referenced by formula fields
• New formula fields — May reference objects the service account can't access
• New lookup fields — Create references to other objects

The recommended approach (View All on all objects) prevents these issues.

---

FAQ

Why does Upside recommend View All on all objects?

The Salesforce API validates access to all objects referenced by field metadata—not just the objects you're syncing. With granular permissions, a single formula field referencing an unexpected object can break the entire sync. View All on all objects eliminates this class of errors entirely.

Does Upside write data to Salesforce?

No. Upside only reads data from Salesforce. The service account only needs View All permissions, never Modify All.

How does this affect my Salesforce API limits?

Upside uses Fivetran, which is designed to minimize API impact:

• Automatically pauses if your org approaches 90% of daily API quota
• Uses Bulk API for large volumes (more efficient than REST)
• Performs incremental syncs after the initial load

See Fivetran's Salesforce documentation for details.

Can I use an existing service account?

Yes, if it has the required permissions. We recommend creating a dedicated user so you can easily audit and modify Upside's access without affecting other integrations.

What if I add new fields to Salesforce?

Contact Upside Support to request a schema re-sync. Upside needs to manually refresh the object schema to pick up new fields—they won't appear automatically.