# 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      |