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

# Salesforce

> Connect Salesforce CRM to your Agent

## Overview

The Salesforce integration enables your agents to query, create, update, and manage records across your entire Salesforce CRM. Works with all standard objects (Accounts, Contacts, Opportunities, etc.) and any custom objects in your org. Two authentication methods are supported: **Username + Password** (no admin setup) and **Connected App (OAuth Client Credentials)** (more secure, recommended for enterprise).

## Features

* **SOQL Queries**: Run any SOQL query with automatic pagination
* **Full CRUD**: Create, read, update, upsert, and delete records on any object
* **Custom Object Support**: Works with custom objects and custom fields (`__c` suffix) out of the box
* **Schema Discovery**: Agents can discover available objects and fields at runtime, including picklist values and relationships
* **Upsert by External ID**: Match and update records using external ID fields for integration workflows
* **Two Auth Methods**: SOAP login (username + password + security token) or OAuth Client Credentials (Connected App), both with session caching and automatic re-authentication on expiry

## Choosing an Authentication Method

* **Username + Password**: simplest setup; works with any standard Salesforce account. Requires a security token that gets reset whenever the user's password changes.
* **Connected App (OAuth)**: requires your Salesforce admin to create a Connected App with the Client Credentials Flow enabled and a "Run-As" user assigned. More secure (no password stored), more stable (no security-token churn), and increasingly required by enterprise security policies.

## Prerequisites

### For Username + Password

* Active Salesforce account (any edition)
* Username, password, and security token for the account
* Appropriate permissions on the objects your agent needs to access

### For Connected App (OAuth)

* A Connected App configured by your Salesforce admin with:
  * OAuth scopes including **Manage user data via APIs (api)**
  * **Client Credentials Flow** enabled with a designated Run-As user
  * The Run-As user has the necessary object/field permissions
* The Consumer Key and Consumer Secret from the Connected App
* Your Salesforce instance URL (e.g., `https://acme.my.salesforce.com` for production or `https://acme--full.sandbox.my.salesforce.com` for a sandbox)

## Setup Guide

<Steps>
  <Step title="Choose Your Authentication Method">
    In Aster Agents, navigate to **Control Hub > Integrations** and locate the Salesforce card. Click **Connect**, then pick **Username + Password** or **Connected App (OAuth)** at the top of the form. The remaining fields update based on your choice.
  </Step>

  <Step title="Configure Connection — Username + Password">
    Skip this step if you chose Connected App.

    First, get your security token: in Salesforce, go to your avatar (top right) > **Settings** > **Reset My Security Token**. Salesforce will email a new token to the email on your account.

    Then provide:

    * **Login URL**: `https://login.salesforce.com` for production, or `https://test.salesforce.com` for sandbox orgs
    * **Username**: Your Salesforce username (email address)
    * **Password**: Your Salesforce account password
    * **Security Token**: The token emailed to you
  </Step>

  <Step title="Configure Connection — Connected App (OAuth)">
    Skip this step if you chose Username + Password.

    Your Salesforce admin must create a Connected App with **Client Credentials Flow** enabled and a Run-As user assigned. From **Setup > App Manager > \[Your App] > View**, copy the Consumer Key and Consumer Secret.

    Then provide:

    * **Instance URL**: Your full Salesforce instance URL (e.g., `https://acme.my.salesforce.com` or `https://acme--full.sandbox.my.salesforce.com`)
    * **Consumer Key**: From the Connected App
    * **Consumer Secret**: From the Connected App
  </Step>

  <Step title="Add Tools to Your Agent">
    Edit your agent and enable the Salesforce tools you need:

    * **Salesforce Query** — run SOQL queries
    * **Salesforce Manage Records** — create, read, update, and delete records
    * **Salesforce Get Schema** — discover objects and field definitions

    We recommend enabling all three — the agent uses Get Schema to learn your org's field names before querying or writing data.
  </Step>
</Steps>

## Available Tools

### Salesforce Query

Execute SOQL queries against your Salesforce org. Results are automatically paginated for large result sets.

```sql theme={null}
SELECT Id, Name, Industry, AnnualRevenue 
FROM Account 
WHERE Industry = 'Technology' 
ORDER BY AnnualRevenue DESC 
LIMIT 10
```

### Salesforce Manage Records

Perform CRUD operations on any standard or custom object:

* **get** — retrieve a record by ID
* **create** — create a new record with field values
* **update** — update specific fields on an existing record
* **upsert** — insert or update based on an external ID field
* **delete** — delete a record by ID

### Salesforce Get Schema

Discover your org's data model at runtime:

* Call without parameters to list all available objects
* Call with an object name to get detailed field information including types, picklist values, required flags, and relationship targets

This is especially useful for orgs with custom objects and fields — the agent learns your schema before making queries.

## Security Considerations

* **Prefer Connected App (OAuth)** for production — no password is stored, and access is bounded by the Run-As user's profile and permission sets
* **Use a dedicated service account / Run-As user** rather than a personal account
* **Apply profile and permission set restrictions** on the Salesforce user to limit which objects and fields the agent can access
* **Enable field-level security** in Salesforce to control access to sensitive fields
* **Monitor login history** in Salesforce Setup to track agent activity
* **Rotate your security token / Consumer Secret** periodically
* **Use sandbox orgs** (`https://test.salesforce.com` for SOAP, or your sandbox instance URL for OAuth) for testing before connecting production

## Troubleshooting

<AccordionGroup>
  <Accordion title="Login Failed (Username + Password)">
    * Verify your username, password, and security token are correct
    * Ensure your account is not locked — check your email for lockout notifications
    * If you recently changed your password, you must reset your security token as well (it changes with every password reset)
    * Confirm you're using the correct Login URL (production vs. sandbox)
  </Accordion>

  <Accordion title="Login Failed (Connected App / OAuth)">
    * Verify the Consumer Key and Consumer Secret are copied exactly from your Connected App (no extra spaces)
    * Confirm the Connected App has the **Client Credentials Flow** enabled and a Run-As user assigned
    * Confirm the OAuth scope includes **Manage user data via APIs (api)**
    * Verify the Instance URL points to the correct environment (sandbox vs. production) — the URL determines which org you authenticate into
    * Check that the Run-As user is active and has access to the API
  </Accordion>

  <Accordion title="Insufficient Permissions">
    * The Salesforce user's profile and permission sets control what objects and fields are accessible
    * Ask your Salesforce admin to verify the user has read/write access to the required objects
    * Check field-level security if specific fields are missing from query results
  </Accordion>

  <Accordion title="Custom Objects Not Found">
    * Custom object API names always end with `__c` (e.g., `Invoice__c`)
    * Use the **Salesforce Get Schema** tool to list all available objects and find the correct API name
    * Managed package objects use a namespace prefix (e.g., `AIM__Deal__c`)
  </Accordion>

  <Accordion title="Security Token Not Working">
    * Security tokens are invalidated whenever you change your password — reset the token after any password change
    * If your org uses IP restrictions and your IP is whitelisted, the security token may not be required — try leaving it blank
    * Check that you're copying the full token from the email (no extra spaces)
  </Accordion>
</AccordionGroup>

## Related Tools

* **Salesforce Query** (`salesforce_query`) - Execute SOQL queries
* **Salesforce Manage Records** (`salesforce_manage_records`) - CRUD operations on any object
* **Salesforce Get Schema** (`salesforce_get_schema`) - Discover objects and fields