> ## Documentation Index
> Fetch the complete documentation index at: https://docs.scoutos.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect Salesforce to Scout: Quick Connect, OAuth, and JWT

> Connect Salesforce to Scout with Quick Connect, a custom OAuth app, or JWT Bearer Flow. Query records with SOQL, manage data, and act as specific users.

Salesforce holds the structured pipeline and account data your agents can act on directly — opportunities, contacts, leads, tasks, and any custom object in your org. Once connected, agents can run SOQL queries, create and update records, and search across objects, all scoped to the authorizing user's permissions. Scout supports both **Production** and **Sandbox** environments.

If your team also uses HubSpot, connect it independently from the [HubSpot integration page](/integrations/hubspot) — an agent can use tools from both CRMs in the same workflow.

## Choosing a Connection Method

Salesforce supports three ways to connect. Pick the one that matches your security requirements.

| Method               | Best for                                                                                                |
| -------------------- | ------------------------------------------------------------------------------------------------------- |
| **Quick Connect**    | Testing and teams without Salesforce admin access — the fastest path                                    |
| **Custom OAuth App** | Enterprise deployments that require their own Connected App and security controls                       |
| **JWT Bearer Flow**  | Server-to-server automation where the agent acts on behalf of a specific user with no interactive login |

## Quick Connect (Recommended)

Quick Connect uses Scout's managed OAuth app, so there's nothing to configure in Salesforce.

<Steps>
  <Step title="Open the Integrations page">
    Go to [studio.scoutos.com/integrations](https://studio.scoutos.com/integrations) and click the **Salesforce** card.
  </Step>

  <Step title="Connect with OAuth">
    Click **Connect with OAuth** and choose your environment — **Production** (login.salesforce.com) or **Sandbox** (test.salesforce.com).
  </Step>

  <Step title="Authorize in Salesforce">
    Sign in to Salesforce, review the requested permissions, and click **Allow**. You'll be redirected back to Scout.
  </Step>

  <Step title="Verify the connection">
    Your workspace should show a green status indicator, the environment type, and the connection date.
  </Step>
</Steps>

## Custom OAuth App

Use a custom Connected App when your security team requires Scout to authenticate through credentials you own and control.

<Note>
  **Prerequisites:** Available across Group through Developer editions, in both Classic and Lightning. You need either `Customize Application` + `Modify All Data`, or `Customize Application` + `Manage Connected Apps`.
</Note>

<Steps>
  <Step title="Enable connected app creation">
    In Salesforce, go to **Setup → External Client App Settings** and turn on the option to allow creation of connected apps. This is a one-time setting per org.
  </Step>

  <Step title="Create a Connected App">
    Click the gear icon → **Setup → App Manager → New Connected App**.
  </Step>

  <Step title="Configure basic information">
    Enter a connected app name, contact email, and (optionally) a logo URL, info URL, and description (256 characters max). The API name fills in automatically.
  </Step>

  <Step title="Enable OAuth settings">
    Turn on OAuth and configure:

    * **Callback URL:** `https://studio.scoutos.com/oauth/salesforce/success`
    * **Scopes:** Full access (`full`), Access the identity URL service, Manage user data via APIs (`api`), Manage user data via Web browsers (`web`), and Perform requests at any time (`refresh_token`, `offline_access`)
    * Enable **Client Credentials Flow** and **Authorization Code and Credentials Flow**
    * Require a secret for the **Web Server Flow** and **Refresh Token Flow**
  </Step>

  <Step title="Copy your credentials">
    Copy the **Consumer Key** (Client ID), then reveal and copy the **Consumer Secret** (Client Secret).
  </Step>

  <Step title="Connect to Scout">
    On the Salesforce card, click **Add Workspace**, check **Use custom Salesforce Connected App credentials**, select your environment, enter your Client ID and Client Secret, and click **Connect with OAuth**.
  </Step>
</Steps>

<Note>
  Salesforce can take a few minutes to activate a newly created Connected App. If authorization fails immediately after setup, wait a few minutes and try again.
</Note>

## JWT Bearer Flow (User-Scoped)

JWT Bearer Flow uses certificate-based authentication so Scout can act as a specific user without an interactive login. It's ideal for scheduled and background jobs.

**Why use it:**

* No user interaction required — authentication happens automatically
* Access is scoped to a specific user
* Uses cryptographic signing instead of stored passwords
* Well suited to scheduled agents and server-to-server automation

<Steps>
  <Step title="Create a private key and certificate">
    Use OpenSSL to generate an RSA private key, a certificate signing request, and a self-signed certificate valid for 365 days:

    ```bash theme={null}
    openssl genrsa -out server.key 2048
    openssl req -new -key server.key -out server.csr
    openssl x509 -req -days 365 -in server.csr -signkey server.key -out server.crt
    ```

    Keep `server.key` secure — anyone with it can authenticate as the connected user.
  </Step>

  <Step title="Create an External Client App with digital signatures">
    Go to **App Manager → New External Client App** and fill in the basics (set **Distribution State** to Local). Enable OAuth, set the callback URL to any HTTPS URL, and add the scopes `api` and `refresh_token, offline_access`. Enable **JWT Bearer Flow** and upload your `server.crt`.
  </Step>

  <Step title="Pre-authorize users">
    Open **External Client App Manager → Policies → Edit**. Set **Permitted Users** to "Admin approved users are pre-authorized" and **IP Relaxation** to "Relax IP restrictions", then add the profiles or permission sets that should be allowed. Only pre-authorized users can authenticate.
  </Step>

  <Step title="Get the Consumer Key">
    Open the app, go to the **OAuth Settings** tab, and copy the **Consumer Key**.
  </Step>

  <Step title="Connect in Scout">
    On the **Salesforce (User Scoped)** card, click **Add Workspace** and complete the checklist. Paste your Consumer Key and the full PEM private key (including its headers), select your environment, and click **Create Connection**. Confirm the workspace shows a green status.
  </Step>
</Steps>

### JWT Troubleshooting

| Issue                     | Solution                                                                                      |
| ------------------------- | --------------------------------------------------------------------------------------------- |
| Invalid JWT token         | Verify the key matches the uploaded certificate and is in PEM format with the correct headers |
| User not pre-authorized   | Add the user's profile or permission set to the approved list                                 |
| Certificate expired       | Generate a new certificate and key, upload to Salesforce, and update the key in Scout         |
| Invalid client identifier | Verify the correct Consumer Key and ensure the app is active                                  |

### JWT Security Best Practices

* Protect your private key and never commit it to source control
* Rotate certificates regularly (typically yearly)
* Grant the minimum permissions the agent needs
* Use separate apps for Production and Sandbox
* Monitor usage logs for unexpected activity

## Verify the Connection

Open an agent, go to the **Tools** tab, and toggle Salesforce on. Then test with a prompt:

* "List the last 5 accounts from Salesforce."
* "Find the contact with email [jane@example.com](mailto:jane@example.com)."
* "Get opportunity by ID and summarize its stage and next steps."
* "How many open opportunities do we have this quarter?"

<Note>
  The authorizing user's Salesforce permissions apply. If a user can't read a field or object in Salesforce, the agent can't either. Check field-level security in Salesforce Setup if the agent returns incomplete records.
</Note>

## Available Capabilities

Once connected and enabled, your agent can:

| Category                | Capabilities                                                     |
| ----------------------- | ---------------------------------------------------------------- |
| **Data querying**       | SOQL queries, SOSL search, list objects, get field metadata      |
| **Record management**   | Get a record by ID, create, update, and delete records           |
| **Advanced operations** | Direct REST API calls, bulk operations, and relationship queries |

## Instruction Guardrails

CRM writes are consequential. A bad update can corrupt a record, create a duplicate, or overwrite data another rep entered. Add this block to your agent's **Instructions** before enabling any write tools:

```markdown theme={null}
For CRM tasks:

1. Look up the record before writing.
2. Match by stable identifier (record ID, email, domain) before updates.
3. Return the CRM object ID, fields changed, and reason after each write.
4. Ask before creating duplicates when confidence is low.
```

## Troubleshooting

| Issue                                  | Solution                                                                               |
| -------------------------------------- | -------------------------------------------------------------------------------------- |
| No permission to create Connected Apps | Contact your admin or use a free Developer Edition org                                 |
| Invalid client credentials             | Verify the Consumer Key and Secret were copied correctly                               |
| Redirect URI mismatch                  | The callback URL must be exactly `https://studio.scoutos.com/oauth/salesforce/success` |
| User hasn't approved the app           | Sign in as an authorized user and check app approval for the profile                   |
| Authentication failure                 | Verify you're using the correct environment (Production vs. Sandbox)                   |
| Token expired                          | Open the Salesforce integration in Scout and click **Reconnect**                       |
| Insufficient privileges                | Ensure proper permissions and object/field-level security                              |
| API limit exceeded                     | Monitor usage in **System Overview** and optimize your queries                         |

## Next Steps

<CardGroup cols={2}>
  <Card title="HubSpot" icon="hubspot" href="/integrations/hubspot">
    Connect HubSpot too — agents can use Salesforce and HubSpot tools in the same workflow.
  </Card>

  <Card title="Slack" icon="slack" href="/integrations/slack">
    Route pipeline summaries and deal alerts from Salesforce to team channels.
  </Card>

  <Card title="Gmail" icon="envelope" href="/integrations/gmail">
    Add email context to Salesforce-driven outreach workflows.
  </Card>

  <Card title="Integrations Overview" icon="grid" href="/integrations/overview">
    See the full integration stack and recommended connection order.
  </Card>
</CardGroup>