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

# Salesforce

> Integrate Salesforce with AirMDR using secure OAuth 2.0 authentication to enable API-based connectivity, automated workflows, alert enrichment, and controlled access to Salesforce data through Connected Apps and Remote Agent support.

## Purpose

The Salesforce integration enables AirMDR to connect with Salesforce using OAuth-based authentication and securely retrieve or act on Salesforce data through approved API access.

This guide explains how to collect the required Salesforce configuration values:

| AirMDR Field | Salesforce Value |
| :- | :- |
| Instance URL | Salesforce org URL / My Domain URL |
| Client ID | Connected App Consumer Key |
| Client Secret | Connected App Consumer Secret |
| Remote Agent | AirMDR remote agent used to route integration traffic, if required |

Salesforce uses Connected Apps to allow external applications to integrate through OAuth and API access..

## Supported Versions

| Component | Supported Details |
| :- | :- |
| Salesforce | Salesforce Lightning Experience |
| Authentication | OAuth 2.0 using Connected App |
| API Access | Salesforce REST API |
| AirMDR Requirement | Valid Salesforce Instance URL, Client ID, Client Secret, and Remote Agent if the customer environment requires agent-based connectivity |

<Note>
  The Salesforce user configuring this integration must have permission to access **Setup**, create or manage **Connected Apps**, and view OAuth consumer details.
</Note>

## Authentication

Salesforce uses OAuth 2.0 credentials generated from a **Connected App**.

| Credential | Description |
| :- | :- |
| Client ID | Salesforce **Consumer Key** generated for the Connected App |
| Client Secret | Salesforce **Consumer Secret** generated for the Connected App |
| Instance URL | Salesforce org URL, usually the My Domain URL |
| OAuth Scopes | Permissions granted to the Connected App |
| Remote Agent | AirMDR agent used when the Salesforce API endpoint must be reached through a customer-managed network path |

<Note>
  Salesforce requires identity verification before viewing the Consumer Key and Consumer Secret in some orgs.
</Note>

### Pre-requisites

> <Check>
>   Users must have Administrator access to the **Salesforce**.
> </Check>
>
> <Check>
>   Dedicated Salesforce Integration User.
> </Check>
>
> <Check>
>   AirMDR Remote Agent and Network Connectivity installed and active (if required by deployment model).
> </Check>

### Configure Salesforce

<Steps>
  <Step title="Retrieve the Salesforce Instance URL">
    1. Log in to the **[Salesforce](https://login.salesforce.com/).**
    2. Copy the base URL from the browser address bar.\
       [https://companyname.my.salesforce.com](https://companyname.my.salesforce.com)
    3. Remove any page-specific path after the domain. Use only the base URL: [https://companyname.my.salesforce.com](https://companyname.my.salesforce.com)
           <Note>
             For sandbox environments, the URL may look similar to `https://companyname--sandbox.sandbox.my.salesforce.com`
           </Note>
  </Step>

  <Step title="Create a Connected App in Salesforce">
    1. Log in to [**Salesforce**](https://login.salesforce.com/) as an administrator.
    2. Click the **Setup** gear icon.
    3. In **Quick Find**, search for **App Manager**.
    4. Select **App Manager**.
    5. Click **New External Client App**.
    6. Enter the basic app details:

    | Field | Recommended Value |
    | :- | :- |
    | External Client App Name | `AirMDR Salesforce Integration` |
    | API Name | Auto-generated |
    | Contact Email | Admin or SOC team email |
    | Distribution State | Local |

    7. Select **Enable OAuth Settings**. (Select the checkbox)
           <Info>
             Salesforce’s Connected App configuration is used to enable OAuth settings for API integration.
           </Info>
  </Step>

  <Step title="Configure OAuth Settings">
    In the **API (Enable OAuth Settings)** section:

    1. Select **Enable OAuth Settings**.
    2. Enter the Callback URL.\
       **Recommended callback URL:**
       ```text theme={null}
       https://login.salesforce.com/services/oauth2/success
       ```
       **For sandbox:**
       ```text theme={null}
       https://test.salesforce.com/services/oauth2/success
       ```
           <Tip>
             [Salesforce documentation](https://help.salesforce.com/s/articleView?id=ind.cg_task_admin_connected_apps.htm\&language=en_US\&type=5\&utm_source=chatgpt.com) lists these callback URLs as valid examples when creating a Connected App.
           </Tip>
    3. Add the required OAuth scopes. Recommended scopes:
       | Scope | Purpose |
       | :- | :- |
       | Full Access | Allows API access to Salesforce data |
       | Perform requests at any time (refresh\_token, offline\_access) | Allows refresh-token based access where applicable |
       | Manage User data via APIs | Required if AirMDR needs API-based user or object access |
           <Note>
             Select only the scopes required for the approved AirMDR use case. Avoid granting broad access unless explicitly required.
           </Note>
    4. In the **Flow Enablement**, select the check box "**Enable Client Credentials Flow**".
    5. In the **Security** section, make sure "**Require secret for Web Server Flow**", and "**Require secret for Refresh Token Flow**" are selected
    6. Click **Create**.
    7. Click **Continue**.
           <Note>
             Salesforce may take a few minutes to apply Connected App changes.
           </Note>
  </Step>

  <Step title="Retrieve the Client ID and Client Secret">
    1. In the **External Client App Manager**, select your application "For example: AirMDR Salesforce Integration".
    2. Go to **Settings** tab.
    3. Select the **OAuth Settings** drop-down.
    4. Under the **App settings**, you can see **Consumer Key and Secret**.
    5. Copy the following values:

    | Salesforce Field | AirMDR Field |
    | :- | :- |
    | Consumer Key | Client ID |
    | Consumer Secret | Client Secret |

    <Note>
      Salesforce identifies the Consumer Key and Consumer Secret as the credentials used by the connected app for OAuth authentication.
    </Note>
  </Step>

  <Step title="Configure Connected App Policies">
    1. In the **External Client App Manager**, select your application "For example: AirMDR Salesforce Integration".
    2. Go to **Policies** tab.
    3. Select the **OAuth Policies** drop-down.
    4. In **OAuth Flows and External Client App Enhancements**
       * Select the **Enable Client Credentials Flow** checkbox
       * In the **Run As (Username)**, enter your Salesforce Username
    5. Click **Save**.

    <Note>
      The App Authorization Refresh Token Validity period is 365 days.
    </Note>
  </Step>
</Steps>

### Validate Connectivity

Use the following sample token request only for validation from an approved secure environment:

<AccordionGroup>
  <Accordion title="Example POST Request using cURL:">
    ```text theme={null}
    curl -X POST "https://login.salesforce.com/services/oauth2/token" \
      -H "Content-Type: application/x-www-form-urlencoded" \
      -d "grant_type=client_credentials" \
      -d "client_id=<client_id>" \
      -d "client_secret=<client_secret>"
    ```
  </Accordion>

  <Accordion title="For sandbox:">
    ```text theme={null}
    curl -X POST "https://test.salesforce.com/services/oauth2/token" \
      -H "Content-Type: application/x-www-form-urlencoded" \
      -d "grant_type=client_credentials" \
      -d "client_id=<client_id>" \
      -d "client_secret=<client_secret>"
    ```
  </Accordion>
</AccordionGroup>

<Note>
  Salesforce supports OAuth 2.0 client credentials flow where the app exchanges its consumer key and consumer secret for an access token.
</Note>

### Configure Salesforce in AirMDR Integrations Dashboard

1. Navigate to [AirMDR](https://app.airmdr.com/auth/login), provide the credentials and click **Login**
2. Navigate to the AirMDR Integrations Dashboard in the left navigation pane and select **Integrations**.
3. Use the search option, enter the keyword "**Salesforce**", select the **Connections** tab, and click **+ Create** button.
4. Enter an unique name to the Instance (e.g., `your org name-Salesforce`) to easily identify the user connection by AirMDR.
5. Enter the application credentials like **Instance URL, Client ID,** and **Client Secret** in the Authentication Details field params, and click **Save**.

### Skills provided by this Integration

| **Skill ID** | **Purpose** |
| :- | :- |
| Create Salesforce Record | Create a new Salesforce sObject record by posting field values to `/sobjectsk/{Typer}/` |
| Get Salesforce Setup Audit Trail | Retrieve Salesforce SetupAuditTrail records with optional filters by time range, duration, user, and action. |
| Get Salesforce Event Log Files | Query Salesforce EventLogFile records and return parsed log entries. Supports filtering by event type, time range, relative duration, and log interval. |
| Delete Salesforce Record | Delete a Salesforce sObject record via `DELETE(sobjects/{Type}/{id}` |
| Get Salesforce Release Notes | Detect the connected orgs latest API version and return the canonical Salesforce release notes URL. |
| Execute Salesforce SOQL Query | Execute a SOQL SELECT statement against Salesforce and return the records (paginated automatically). Only SELECT queries are allowed. |
| Get Salesforce Report | Fetch a Salesforce Analytics report by Id. Returns reportMetadata, factMap, groupingsAcross, and groupingsDown. |
| Upsert Salesforce Record | Upsert (create or update) a Salesforce sObject record by an external Id field via `PATCH /sobjects/{Type}/{ExternalldField}/{value}` |
| Update Salesforce Record | Update an existing Salesforce sObject record via `PATCH /sobjects/{Type}/{id}` |
| List Salesforce Event Types | List the distinct EventTypes available in the Salesforce organizations EventLogFile. |

<Tip>
  To view the details of Input Parameters and Output for the respective skills

  * Go to [AirMDR → Salesforce](https://app.airmdr.com/integrationsv2/147e048d-ece3-49fe-8cc2-4ab821625235/skills?search=sales) Integration page.
  * Select the **Skills** tab and click on the required listed skills.
</Tip>

## Additional Information

<AccordionGroup>
  <Accordion title="🧰 Error Handling">
    | Error | Possible Cause | Recovery |
    | :- | :- | :- |
    | Invalid Client ID | Incorrect Consumer Key copied | Reopen Connected App and copy the Consumer Key again |
    | Invalid Client Secret | Secret copied incorrectly or rotated | Generate or retrieve the current Consumer Secret |
    | Invalid Grant | OAuth flow not enabled or policy mismatch | Review Connected App OAuth settings |
    | Access Denied | User lacks required permission | Assign Connected App access through profile or permission set |
    | Instance URL Unreachable | Wrong URL or network issue | Validate My Domain URL and Remote Agent connectivity |
    | API Permission Error | Missing OAuth scope or Salesforce permission | Add required scope or permission to integration user |
  </Accordion>

  <Accordion title="🔄 Monitoring & Logs">
    ### Salesforce Monitoring

    Use the following Salesforce areas for monitoring:

    | Location | Purpose |
    | :- | :- |
    | Setup → Login History | Review authentication attempts |
    | Setup → Connected Apps OAuth Usage | Review OAuth app usage |
    | Setup → Event Monitoring | Review API and security events, if licensed |
    | Setup → Debug Logs | Troubleshoot user-level execution issues |

    ### AirMDR Monitoring

    In AirMDR:

    1. Go to **Integrations**.
    2. Open the **Salesforce** integration.
    3. Review connection status.
    4. Check recent sync or execution logs.
    5. Validate any failed authentication or API request errors.

    Sample log:

    ```text theme={null}
    INFO  Salesforce integration initialized
    INFO  OAuth token request submitted
    INFO  Salesforce API connection successful
    ERROR Salesforce authentication failed: invalid_client_id_or_secret
    ```

    | Environment | Recommended Level |
    | :- | :- |
    | Production | INFO / WARN |
    | Troubleshooting | DEBUG temporarily |
    | Security Review | Audit logs enabled |
  </Accordion>

  <Accordion title="🛑 Security & Access Best Practices">
    * Use a **dedicated Salesforce integration or service account** instead of a personal user account exclusively for AirMDR integration
    * Store the Salesforce **Client ID** and **Client Secret** securely using approved secret-management solutions. Never expose credentials in emails, tickets, screenshots, or shared documentation
    * Enable Multi-Factor Authentication (MFA) for Salesforce administrator accounts managing Connected Apps and integration settings.
    * Configure Connected App policies to allow only approved users, profiles, or permission sets to access the integration. **Monitor Authentication Activity**
      * Regularly review:
        * Salesforce Login History
        * Connected App OAuth Usage
        * AirMDR integration logs
        * Failed authentication attempts
    * Rotate Secrets Periodically Rotate the Salesforce Consumer Secret periodically based on organizational security policies or after any suspected credential exposure.
    * Validate Remote Agent Connectivity If a Remote Agent is used, ensure it is deployed in a secure environment with controlled outbound network access to Salesforce endpoints only.
    * Enforce Secure Communication Ensure all communication between AirMDR and Salesforce occurs over encrypted HTTPS/TLS connections.
    * Review Integration Permissions Regularly Conduct periodic reviews of:
      * OAuth scopes
      * User permissions
      * Connected App policies
      * Remote Agent assignments
  </Accordion>

  <Accordion title="👉 Support & Maintenance">
    * 📧 Contact [**AirMDR Support**](mailto:support@airmdr.com) through your designated support channel.
    * 🔁 Rotate credentials regularly.
    * 🔄 Reconnect in AirMDR when secrets are changed.
    * For integration issues, collect the following before contacting support:
      ```text theme={null}
      Salesforce Instance URL
      Connected App name
      Timestamp of failed connection
      AirMDR integration error message
      Remote Agent name, if applicable
      Salesforce login or OAuth error details
      ```
          <Note>
            Do not share the Client Secret in support tickets. Share only masked values when required.
          </Note>
  </Accordion>
</AccordionGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.