Salesforce Connector Setup

Overview

The Salesforce connector extracts CRM data -- Opportunities, Accounts, Contacts, Contracts, Users, and line items -- using the REST API and Bulk API 2.0. Authentication uses the JWT Bearer flow, which provides server-to-server access without interactive login or refresh tokens.

VersionForge automatically selects the optimal API for each extraction: REST for small incremental pulls, Bulk API 2.0 for full extracts or large result sets (over 10,000 rows by default).

Prerequisites

• Salesforce org with API access enabled and My Domain configured
• Administrator or equivalent permissions to create Connected Apps and manage OAuth policies
• OpenSSL or equivalent tool for generating RSA key pairs

Credential Fields

| Field | Required | Description | |-------|----------|-------------| | instanceUrl | Yes | Your Salesforce org URL, e.g. https://yourorg.my.salesforce.com. Found in Setup > My Domain. | | clientId | Yes | Consumer Key from the Connected App you create in Step 1. | | username | Yes | Email address of the Salesforce user pre-authorized in the Connected App. | | privateKey | Yes | RSA private key (PEM format) matching the X.509 certificate uploaded to the Connected App. Include the full BEGIN/END PRIVATE KEY markers. |

Setup Steps

1. Create a Connected App

   Navigate to Setup > App Manager > New Connected App. Fill in:

   • Connected App Name: e.g. "VersionForge Integration"
   • API Name: auto-populates
   • Contact Email: your admin email

   Under API (Enable OAuth Settings):

   • Check Enable OAuth Settings
   • Set Callback URL to https://localhost (required by Salesforce but not used in the JWT flow)
   • Check Use Digital Signatures and upload your X.509 certificate (see Step 4)

   Click Save. The app may take 2-10 minutes to activate.

   The Consumer Key (Client ID) is shown on the Connected App detail page after saving. Copy it immediately.

2. Configure OAuth Scopes

   Edit the Connected App and add these OAuth scopes:

   • Access and manage your data (api) -- required for SOQL queries and Bulk API
   • Perform requests on your behalf at any time (refresh_token, offline_access) -- required for the JWT Bearer flow

3. Pre-Authorize the Integration User

   Under the Connected App's Manage page:

   1. Set Permitted Users to "Admin approved users are pre-authorized"
   2. Under Profiles or Permission Sets, add the Profile or Permission Set assigned to your integration user

   This allows the integration user to authenticate via JWT without an interactive login prompt.

4. Generate an RSA Key Pair

   Run the following command to generate a self-signed certificate and private key:

   openssl req -x509 -sha256 -nodes -days 365 -newkey rsa:2048 \
     -keyout server.key -out server.crt -subj "/CN=VersionForge"
   

   Upload server.crt to the Connected App (Step 1). Keep server.key secure -- you will paste its contents in the next step. The certificate is valid for 365 days; rotate before expiry.

5. Configure the Credential in VersionForge

   Navigate to Dashboard > Connections > Add Connection and select Salesforce. Follow the guided setup wizard and enter your instanceUrl, clientId, username, and the contents of server.key as the private key.

Test Your Connection

After saving, VersionForge automatically validates by:

1. Signing a JWT with your private key and exchanging it for an access token
2. Calling the Salesforce API versions endpoint to confirm connectivity

A successful test confirms your Connected App is configured correctly and the integration user is pre-authorized.

Common Issues

invalid_grant on JWT exchange -- The most common cause is that the integration user is not pre-authorized in the Connected App's OAuth Policies. Verify Step 3. Also confirm the username matches the exact email on the Salesforce user record.

invalid_client_id -- The clientId (Consumer Key) does not match any Connected App in the target org. Double-check you copied the correct key, and that the Connected App has finished activating (can take up to 10 minutes).

authentication failure or invalid assertion -- The private key does not match the certificate uploaded to the Connected App. Regenerate the key pair and re-upload the certificate.

API quota warnings -- VersionForge checks your org's daily API request limits before each extraction. If remaining quota drops below 1,000 calls, a warning is logged. For large orgs with high API usage, consider a dedicated integration user with its own API allocation.