> For the complete documentation index, see [llms.txt](https://docs.stackai.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.stackai.com/integrations/catalog/salesforce/configure-salesforce-authentication.md).

# Configure Salesforce authentication

### Setting Up A Credentials Connection

1. **Obtain your login credentials**:
   * **Username**: your Salesforce login name.
   * **Password**: your Salesforce account password.

![Configure Salesforce authentication setup](https://1957915746-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSQ1Sgy933krTyK0S4JpP%2Fuploads%2FHUXI5OWq1aaPbUWD3STt%2Fimage.png?alt=media)

2. After logging in, click on your profile picture on the upper right.

![Configure Salesforce authentication setup](https://1957915746-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSQ1Sgy933krTyK0S4JpP%2Fuploads%2FCZdIDc1x1f8BfUDKl248%2Fimage.png?alt=media)

3. A dropdown menu will appear, click on **Settings**.

![Configure Salesforce authentication setup](https://1957915746-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSQ1Sgy933krTyK0S4JpP%2Fuploads%2F7lKB9h5hzeWMYc1cb5BK%2Fimage.png?alt=media)

4. On the **Settings** page, on the left navigation, select **Reset My Security Token**.

![Configure Salesforce authentication setup](https://1957915746-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSQ1Sgy933krTyK0S4JpP%2Fuploads%2Ff1j7R7z5v0qIZwNDWJhE%2Fimage.png?alt=media)

5. Click on **Reset Security Token**.

![Configure Salesforce authentication setup](https://1957915746-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSQ1Sgy933krTyK0S4JpP%2Fuploads%2FyySzkTTa6dgcTZbgtpZs%2Fimage.png?alt=media)

6. On click, the new Security token will be sent to the email associated to your Salesforce account.

![Configure Salesforce authentication setup](https://1957915746-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSQ1Sgy933krTyK0S4JpP%2Fuploads%2F5mg7i4m5D2i6oDuCkLS3%2Fimage.png?alt=media)

7. Finally, in the email, this will be the **Security token** that will be used for the connection.

![Configure Salesforce authentication setup](https://1957915746-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSQ1Sgy933krTyK0S4JpP%2Fuploads%2FJbBgoDr0rV6yhnhrJrOL%2Fimage.png?alt=media)

#### Steps to connect:

1. Add the **Salesforce node** from the Apps section into your StackAI project.

![Configure Salesforce authentication setup](https://1957915746-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSQ1Sgy933krTyK0S4JpP%2Fuploads%2FRlcUOs7yi1obRwQQZLR7%2Fimage.png?alt=media)

2. Select **"Query Salesforce"** as the Action.

![Configure Salesforce authentication setup](https://1957915746-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSQ1Sgy933krTyK0S4JpP%2Fuploads%2Fh51twrd3VcztoDypj2Uo%2Fimage.png?alt=media)

3. Click on **"Select a connection"** or create a new connection with your credentials.

![Configure Salesforce authentication setup](https://1957915746-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSQ1Sgy933krTyK0S4JpP%2Fuploads%2Fs6pntcSeBpcJuMf3AT29%2Fimage.png?alt=media)

4. Choose the appropriate domain for your Salesforce environment:

   | Domain                | Use When                                                    |
   | --------------------- | ----------------------------------------------------------- |
   | "login" or left blank | Connecting to production or developer orgs                  |
   | "test"                | Connecting to a sandbox instance                            |
   | mycustomdomain        | Using a custom domain (recommended for SSO or OAuth setups) |

![Configure Salesforce authentication setup](https://1957915746-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSQ1Sgy933krTyK0S4JpP%2Fuploads%2FaLzJ27HVhMWXprkxQPS5%2Fimage.png?alt=media)

{% hint style="info" %}
Note that the Username for your API is different from the email address you used to sign up for Salesforce.
{% endhint %}

* **Enabling the "sandbox" toggle** tells StackAI to connect to your Salesforce **sandbox environment** instead of your main (production) Salesforce account.
* **Disabling the "sandbox" toggle** means StackAI will connect to your **production** Salesforce environment.

5. **Add your Salesforce Schema** in the configurations of the node to define which table you want to extract.
   * For example: TABLE Contact (Id TEXT, Name TEXT, Industry TEXT);

     ![Configure Salesforce authentication setup](https://1957915746-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSQ1Sgy933krTyK0S4JpP%2Fuploads%2FGhYueTiRXR02BR4iPltD%2Fimage.png?alt=media)
   * To list tables from your Salesforce account, you can run the included Python script below on your local machine.

<details>

<summary>Show Python Script</summary>

{% code title="list\_salesforce\_schema\_with\_filter.py" lineNumbers="true" fullWidth="true" %}

```python
from simple_salesforce import Salesforce

# Salesforce credentials (replace with environment variables in production)
username = ""
password = ""
security_token = ""

# 🔍 Specify object names to include (DANGER leaving the list empty will include ALL)
included_objects = ["Contact", "Account", "Opportunity"]  # Case-sensitive

# Connect to Salesforce
sf = Salesforce(username=username, password=password, security_token=security_token)

# Mapping Salesforce field types to SQL types
def map_salesforce_type(sf_type):
    mapping = {
        "string": "TEXT",
        "textarea": "TEXT",
        "picklist": "TEXT",
        "id": "VARCHAR(18)",
        "boolean": "BOOLEAN",
        "int": "INTEGER",
        "double": "FLOAT",
        "currency": "DECIMAL(18,2)",
        "percent": "DECIMAL(5,2)",
        "date": "DATE",
        "datetime": "TIMESTAMP",
        "email": "TEXT",
        "phone": "TEXT",
        "url": "TEXT",
        "reference": "VARCHAR(18)",
        "base64": "BYTEA",
        "location": "TEXT",
    }
    return mapping.get(sf_type, "TEXT")


# Get all object descriptions
objects = sf.describe()["sobjects"]

# Open file for writing schema output
with open("salesforce_schema.txt", "w") as file:
    for obj in objects:
        obj_name = obj["name"]
        
        # Apply filter if specified
        if included_objects and obj_name not in included_objects:
            continue
        
        try:
            obj_details = sf.__getattr__(obj_name).describe()
            field_defs = []

            for field in obj_details["fields"]:
                field_name = field["name"]
                field_type = map_salesforce_type(field["type"])
                field_defs.append(f"{field_name} {field_type}")

            field_list = ", ".join(field_defs)
            table_def = f"TABLE {obj_name} ({field_list});"
            print(table_def)
            file.write(table_def + "\n")

        except Exception as e:
            error_msg = f"-- Could not process {obj_name}: {e}"
            print(error_msg)
            file.write(error_msg + "\n")

print("\nFiltered schema has been saved to 'salesforce_schema.txt'")

```

{% endcode %}

</details>

## **Setting Up An OAuth2 Connector + Connection:**

1. Navigate to **Setup** (the gear in the top right corner), enter `App Manager` in the Quick Find box, and click **New External Client App** in the top right corner.

![Configure Salesforce authentication setup](https://1957915746-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSQ1Sgy933krTyK0S4JpP%2Fuploads%2FtaXK83ICR0qbKDNjlBxR%2Fsalesforce_client.png?alt=media)

2. Name the app and fill out the required information.
3. Ensure you select **Enable OAuth** under Enable OAuth Settings.
4. Type in your callback url. It should be the base web URL followed by `/auth`. For our Cloud offering, the URL is `https://www.stackai.com/auth`
5. Add the permissions your client needs. At minimum, usually `Access and manage your data (api)` and `Perform requests on your behalf at any time (refresh_token, offline_access)` are required.
6. Under **Flow Enablement**, toggle on at least **Enable Authorization Code Flow**
7. Under Security, select **Enable Refresh Token Rotation**, this will allow us to keep your connection alive.
8. Click **Create**
9. Go to Settings of your created app. Under OAuth settings, go to **Consumer Key and Secret.**
10. Save the key and secret you see here.

#### Salesforce OAuth2 Connector

In StackAI, go to **Connectors** in Settings. Search for Salesforce, and create a new **OAuth2 Connector**. Enter the key and secret you got from Salesforce here and click **Create.**

![Configure Salesforce authentication setup](https://1957915746-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSQ1Sgy933krTyK0S4JpP%2Fuploads%2F5UFiO0jyaRy2GG7l9JJJ%2Fsalesforce_connector.png?alt=media)

To establish a connection, select the new Connector you created in any connection dialog window, you will be automatically redirected to sign in to Salesforce, or logged in automatically if you are signed in already.

### Visual overview

![Configure Salesforce authentication setup](https://1957915746-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSQ1Sgy933krTyK0S4JpP%2Fuploads%2FmYY1J0RYCPHA1LdM5Mf0%2Fimage.png?alt=media)

Below are some examples of valid SQL queries for your Salesforce database, provided that it has been included in the **Schema**:

```sql
SELECT Name, Email FROM Contact
```

```sql
SELECT Id, Email FROM Contact WHERE Income > USD10000
```

```sql
SELECT Id, Email FROM Contact WHERE LastName = 'Aceituno'
```

```sql
SELECT Id, Email, Name, ParentAccount.Name FROM Contact
```

## Connection fields and action reference

See [Salesforce](https://docs.stackai.com/integrations/catalog/salesforce.md) for the current connector fields and supported actions.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.stackai.com/integrations/catalog/salesforce/configure-salesforce-authentication.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
