Salesforce
How to configure Salesforce as a destination in Mage to write records using OAuth or username/password authentication with support for insert, update, upsert, and bulk actions.
Overview
Use Salesforce as a destination in Mage to export records into standard or custom Salesforce objects. Mage supports both OAuth 2.0 and username/password/token authentication methods, and enables insert, update, upsert, delete, and hard_delete actions.
You can also configure behavior for bulk failures, define external ID fields for upserts, and optionally override the source-to-object mapping using table_name.
Configuration Parameters
| Key | Description | Required |
|---|---|---|
client_id | OAuth client ID from your Salesforce connected app. | Optional |
client_secret | OAuth client secret from your connected app. | Optional |
refresh_token | OAuth refresh token. Used to obtain new access tokens. | Optional |
username | Username used for Salesforce username/password authentication. | Optional |
password | Corresponding Salesforce password. | Optional |
security_token | Salesforce security token (needed with password-based login). | Optional |
domain | Salesforce domain to authenticate against. Use login (default), test (sandbox), or a custom My Domain. | ✅ |
action | Default operation to perform on incoming records: insert, update, upsert, delete, or hard_delete. | ✅ |
external_id_name | External ID field for upsert operations. Default is "Id". | Optional |
allow_failures | If true, failed records will be skipped and processing will continue. Default is false. | Optional |
table_name | Override the source stream name with a specific Salesforce object name (e.g., Account, Contact, Opportunity). | Optional |
Authentication Options
You can authenticate to Salesforce using either of the following methods:
Option 1: OAuth 2.0
- Set
client_id,client_secret, andrefresh_token. - Recommended for connected apps and secure access with refreshable tokens.
- How to obtain credentials →
Option 2: Username / Password
- Set
username,password, andsecurity_token. - Recommended for sandbox/testing environments.
- Ensure that IP restrictions are disabled or add your Mage IP to the trusted IP list.
Limitations
To map a non-default source stream to a specific Salesforce object, you must explicitly set the table_name parameter in your configuration.
- The value of
table_namemust match the API name of a Salesforce object (e.g.,Account,Lead,Opportunity, or custom objects likeMyObject__c).
Allow Failures Behavior
When allow_failures is set to true:
- Records that are eligible (i.e., match the Salesforce object schema and are valid for the selected action) but fail to commit will be skipped.
- The pipeline will continue processing other records.
When allow_failures is set to false:
- Any failed record will raise an error and halt the pipeline.