> For the complete documentation index, see [llms.txt](https://docs.darcyiq.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.darcyiq.com/build/integration-overview/enterprise/salesforce-integration.md).

# Salesforce Integration

DarcyIQ integrates with Salesforce to link projects and work directly to your customer accounts, enabling seamless customer context and activity tracking.

## Benefits

| Benefit                  | Description                                                    |
| ------------------------ | -------------------------------------------------------------- |
| **Customer Context**     | Automatically associate work with Salesforce accounts          |
| **Activity Tracking**    | Record key activities and insights directly to customer notes  |
| **Seamless Integration** | Work naturally while DarcyIQ manages the Salesforce connection |
| **Data Security**        | Minimal required permissions ensure security best practices    |

## OAuth Authentication

DarcyIQ uses secure OAuth authentication to connect to your Salesforce account:

1. **OAuth Authorization**
   * Secure, industry-standard authentication
   * No need to share passwords with DarcyIQ
   * Granular permission control
2. **Service Account Recommended**
   * Create a dedicated Salesforce user for DarcyIQ
   * Configure appropriate access levels
   * Easier permission management and auditing

## Access Requirements

| Access Type       | Level     | Purpose                               |
| ----------------- | --------- | ------------------------------------- |
| **Account Data**  | Read-only | View customer information and context |
| **Account Notes** | Write     | Update activity and insight tracking  |
| **Contacts**      | Read-only | Access customer contact information   |
| **Opportunities** | Read-only | View related opportunities            |

## Setup Steps

### Step 1: Create Connected App in Salesforce

A Salesforce administrator must first create a Connected App to enable OAuth integration:

{% hint style="info" %}
**Need additional help?** Follow Salesforce's official guide: [Create a Connected App](https://help.salesforce.com/s/articleView?id=sf.connected_app_create.htm\&type=5) for detailed screenshots and explanations.
{% endhint %}

{% stepper %}
{% step %}
**Navigate to Setup** Log into Salesforce as an administrator and go to Setup
{% endstep %}

{% step %}
**Access App Manager** In the Quick Find box, type "App Manager" and select it
{% endstep %}

{% step %}
**Create New Connected App** Click "New Connected App" and configure the basic information:

* **Connected App Name**: DarcyIQ
* **API Name**: DarcyIQ (auto-populated)
* **Contact Email**: Your admin email address
* **Description**: DarcyIQ accelerates your sales and solution architecture team to deliver proposals to profit in minutes not weeks.
  {% endstep %}

{% step %}
**Configure OAuth Settings** Under "API (Enable OAuth Settings)":

* ✅ Check "Enable OAuth Settings"
* **Callback URL**: Add these URLs:
  * `https://api.darcyiq.com/api/oauth/callback`
* **Selected OAuth Scopes**: Add these scopes:
  * "Manage user data via APIs (api)"
  * "Perform requests at any time (refresh\_token, offline\_access)"
    {% endstep %}

{% step %}
**Save and Note Credentials** After saving, you'll receive:

* **Consumer Key**: Used by DarcyIQ for OAuth
* **Consumer Secret**: Keep secure for OAuth flow
  {% endstep %}
  {% endstepper %}

### Step 2: User Authorization

Once the Connected App is configured, individual users can authorize DarcyIQ:

1. **Access DarcyIQ Integrations**
   * Go to <https://app.darcyiq.com/user-configuration#integrations>
   * Select "Salesforce Integration"
2. **OAuth Authorization**
   * Click "Authorize with Salesforce"
   * Log into your Salesforce account when prompted
   * Review and approve the requested permissions:
     * Access your basic information
     * Manage your data via APIs
     * Perform requests at any time
   * Complete the OAuth authorization process
3. **Verify Connection**
   * Confirm successful authorization in DarcyIQ
   * Test the integration with a sample query

## Automatic Account Association

Once configured, DarcyIQ will:

* Automatically detect customer context in your work
* Link activities to the correct Salesforce accounts
* Update account notes with relevant insights
* Maintain activity history for future reference

## Security Best Practices

### Connected App Security

1. **Consumer Key Protection**
   * Keep Consumer Key and Secret secure
   * Don't share credentials outside IT/Admin team
   * Regularly rotate Consumer Secret if needed
2. **OAuth Scope Management**
   * Grant only necessary OAuth scopes
   * Review scope requirements periodically
   * Remove unused permissions
3. **User Access Control**
   * Users authenticate with their own Salesforce credentials
   * No shared service accounts required
   * Individual permission control per user

## Troubleshooting

### Common Setup Issues

| Issue                         | Cause                  | Solution                             |
| ----------------------------- | ---------------------- | ------------------------------------ |
| **"Invalid Client" Error**    | Incorrect Consumer Key | Verify Consumer Key in Connected App |
| **"Invalid Grant" Error**     | Wrong callback URL     | Check callback URLs match exactly    |
| **"Insufficient Privileges"** | User lacks permissions | Review user's Salesforce permissions |
| **Authorization Fails**       | OAuth scopes missing   | Add required scopes to Connected App |

### Connected App Issues

| Issue                       | Solution                                                               |
| --------------------------- | ---------------------------------------------------------------------- |
| **App not appearing**       | Wait 2-10 minutes after creating Connected App                         |
| **Consumer Secret missing** | Click "Click to reveal" in Connected App settings                      |
| **Callback URL mismatch**   | Ensure both production and development URLs are added                  |
| **Scope errors**            | Verify "api" and "refresh\_token, offline\_access" scopes are selected |

### User Authorization Issues

| Issue                    | Solution                                               |
| ------------------------ | ------------------------------------------------------ |
| **Login loop**           | Clear browser cache and cookies                        |
| **Permission denied**    | Check user has necessary Salesforce object permissions |
| **Token expired**        | User needs to re-authorize in DarcyIQ                  |
| **Wrong Salesforce org** | Ensure user logs into correct Salesforce instance      |


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.darcyiq.com/build/integration-overview/enterprise/salesforce-integration.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.