How do I connect Salesforce?

TL;DR: To let Ballet pull live Salesforce data (Opportunity, Contract, Line Items, Contact Roles, and more), create a Salesforce Connected App with OAuth 2.0 Client Credentials Flow, set a Run As integration user, and share your My Domain URL plus Consumer Key and Secret. Use a Flow HTTP callout instead when Salesforce only needs to push events into a Ballet webhook.

Back to: How do I connect CRM and support tools?

Which setup do you need?

This article focuses on outbound API. The inbound path is summarized at the end.

Outbound API: Connected App (Client Credentials)

What you will need

• Salesforce System Administrator access (or equivalent)

• Permission to create a Connected App (or External Client App)

• A dedicated Salesforce integration user (recommended)

• About 15–20 minutes

What you will share with Ballet

Share the Consumer Secret through a secure channel.

Step 1: Create an integration user

1. In Salesforce, open Setup.
2. Go to Users → Users → New User.
3. Create a user such as Ballet Integration.
4. Assign a profile or permission set that includes API Enabled and read access to the objects and fields Ballet needs.
5. Make sure the user is Active.

Use least privilege where possible.

Step 2: Create the Connected App

1. In Setup, go to App Manager.

2. Click New Connected App. If your org shows New External Client App, use that instead.

3. Enter Connected App Name: Ballet, leave the API Name default, and set your admin Contact Email.

4. Under API (Enable OAuth Settings):

   • Select Enable OAuth Settings

   • Set Callback URL to https://api.ballet.dev/auth/salesforce/callback (required by Salesforce; unused for Client Credentials)

   • Select Enable Client Credentials Flow

   • Under Selected OAuth Scopes, add only Manage user data via APIs (api)

5. Do not add Perform requests at any time (refresh_token, offline_access) — that scope breaks Client Credentials.

6. Click Save and wait a few minutes for activation.

Step 3: Set the Run As user

1. In Setup, go to Manage Connected Apps.
2. Open the Ballet Connected App and click Edit Policies.
3. Under Client Credentials Flow, set Run As to your integration user.
4. If available, set Permitted Users to Admin approved users are pre-authorized.
5. Assign the integration user's permission set to the Connected App if prompted, then Save.

If this step is skipped, authentication fails with: invalid_grant: no client credentials user enabled

Step 4: Copy the Consumer Key and Secret

1. Open the Connected App → Manage Consumer Details.
2. Complete identity verification if prompted.
3. Copy Consumer Key (Client ID) and Consumer Secret (Client Secret).

Treat the Consumer Secret like a password. Store it in Ballet Secrets.

Step 5: Find your My Domain URL

1. In Setup, search for My Domain.
2. Copy your org URL (Production: https://yourcompany.my.salesforce.com, Sandbox: https://yourcompany--partial.sandbox.my.salesforce.com).

Step 6: Optional connection test

curl -X POST "https://YOUR_MY_DOMAIN/services/oauth2/token" \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CONSUMER_KEY" \
  -d "client_secret=YOUR_CONSUMER_SECRET"

A successful response includes an access_token.

<br />

---

Outbound API: Pipedream Single Sign-On (SSO)

What you will need

• Salesforce System Administrator access to install packages for the initial sign in.
• About 5 minutes

Step 1: Connect using the built-in Salesforce connector

1. In Ballet → Connectors, search for Salesforce.
2. Select Sign in with Salesforce option.

Step 2: Install Pipedream package

1. When the pop up shows up, press Continue.

2. On the second page, click the link to install the package in your org.

   

3. You will be redirected to Salesforce. Select Install for All Users and install the package.

Step 3: Verify package installation

1. In Salesforce, navigate to Setup → Search and look for Installed Packages and verify that Pipedream is installed.

2. In Setup, search for External Client App Manager and verify that Pipedream is in the list.

---

<br />

Step 4: Continue sign in

1. Once the package is installed, go back to Ballet and continue the sign in process.
2. You will be redirected to a Salesforce pop up - enter your credentials.
3. Once authorized, you will see this message:

---

Troubleshooting

Official Salesforce references

• OAuth 2.0 Client Credentials Flow

• Using the Client Credentials Flow for Easier API Authentication

• Connected App usage restrictions (Pipedream SSO flow)

Inbound webhook: Flow HTTP callout (optional)

Use this when Salesforce should start a Ballet playbook.

1. In Ballet, add a Webhook trigger and choose the Salesforce provider. Copy the trigger URL and store the bearer token in Secrets.
2. In Salesforce, create a Named Credential / Flow HTTP Callout pointing at that URL with Authorization Bearer <token>.
3. Send the record payload as JSON.

See: How do I trigger and react to playbooks with webhooks?