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

# OAuth 2.0

> Connect Parable to Salesforce using OAuth 2.0 Connected App

export const platform_1 = "Salesforce"

export const limit_0 = "API call limits vary by edition; check your org limits in Setup"

export const platform_0 = "Salesforce"

export const role_0 = undefined

<Tabs>
  <Tab title="Setup">
    <Card title="What You'll Need" icon="key">
      | Credential        | What it is                                                                                       |
      | ----------------- | ------------------------------------------------------------------------------------------------ |
      | **Client ID**     | Consumer Key from Connected App                                                                  |
      | **Client Secret** | Consumer Secret from Connected App                                                               |
      | **My Domain**     | Your Salesforce My Domain subdomain (e.g., `acme` — the `acme` part of `acme.my.salesforce.com`) |
    </Card>

    ## Overview

    Connect Parable to Salesforce using a Connected App with the **OAuth 2.0 Client Credentials** flow. This server-to-server flow lets Parable authenticate directly without interactive user login.

    <CardGroup cols={2}>
      <Card title="CRM Data" icon="users">
        Users, accounts, contacts, opportunities
      </Card>

      <Card title="Metadata & Reports" icon="chart-bar">
        Object schemas, reports, dashboards
      </Card>
    </CardGroup>

    ## Prerequisites

    <Info>
      **Setup access in {platform_0}.** These steps require **{role_0}**, or a colleague with equivalent permissions who can create credentials for you.

      If that is not you, ask your {platform_0} administrator.
    </Info>

    * **System Administrator** profile or equivalent permissions
    * Permission to create Connected Apps
    * API access enabled for your organization
    * **My Domain** enabled (required for client credentials flow)

    ## Setup Guide

    <Steps>
      <Step title="Navigate to App Manager">
        1. Log in to Salesforce
        2. Click the **gear icon** → **Setup**
        3. Search for "App Manager" in Quick Find
        4. Click **App Manager**
      </Step>

      <Step title="Create Connected App">
        1. Click **New Connected App**
        2. Fill in basic information:

        | Field              | Value                 |
        | ------------------ | --------------------- |
        | Connected App Name | `Parable Integration` |
        | API Name           | `Parable_Integration` |
        | Contact Email      | Your admin email      |
      </Step>

      <Step title="Enable OAuth Settings">
        1. Check **Enable OAuth Settings**
        2. Set **Callback URL**: `https://login.salesforce.com/services/oauth2/callback` (placeholder — not used by client credentials flow)
        3. Under **Selected OAuth Scopes**, add only:
           * `Manage user data via APIs (api)`

        <Info>
          Only the `api` scope is required and sufficient. Do not add `Full access (full)` or `Perform requests at any time (refresh_token, offline_access)` — the client credentials flow never issues a refresh token, and as of Salesforce Winter '26 (Sept 2025), a missing or invalid-only scope set returns `invalid_grant: no valid scopes defined`.
        </Info>
      </Step>

      <Step title="Enable Client Credentials Flow">
        1. After saving, go back to your Connected App
        2. Click **Manage** → **Edit Policies**
        3. Under **Client Credentials Flow**, check **Enable Client Credentials Flow**
        4. Set the **Run As** user to a dedicated **Integration User** (not a personal admin) — see required permissions below
        5. Click **Save**

        <Warning>
          The "Run As" user determines the permissions for all API calls. Use a dedicated integration user, not a personal admin account.
        </Warning>

        **Run-As User — required object permissions (Read on each):**

        | Object                                                                      | Purpose                    |
        | --------------------------------------------------------------------------- | -------------------------- |
        | User                                                                        | User directory             |
        | LoginHistory                                                                | Login audit                |
        | Event                                                                       | Calendar / activity events |
        | Account, Contact, Opportunity, OpportunityLineItem, OpportunityFieldHistory | CRM core                   |
        | Task                                                                        | Activities                 |
        | Product2                                                                    | Product catalog            |
        | Contract, ContractHistory                                                   | Contract lifecycle         |

        The user profile / permission set must also have **API Enabled** and **View Setup and Configuration** system permissions.
      </Step>

      <Step title="Save and Wait">
        1. Click **Save**
        2. Wait 2-10 minutes for the app to activate

        <Warning>
          Salesforce may take several minutes to propagate the new Connected App.
        </Warning>
      </Step>

      <Step title="Get Consumer Credentials">
        1. Return to **App Manager**
        2. Find your app → Click the dropdown → **View**
        3. Click **Manage Consumer Details** (may require re-authentication)
        4. Copy:
           * **Consumer Key** (Client ID)
           * **Consumer Secret** (Client Secret)
        5. Find your **My Domain** subdomain: go to **Setup → My Domain**. Under **My Domain Details**, note the value before `.my.salesforce.com` (e.g., `acme` from `acme.my.salesforce.com`).
      </Step>

      <Step title="Enter values in the form">
        1. **Client ID**, **Client Secret**, and **My Domain**: Paste the Consumer Key, Consumer Secret, and My Domain subdomain from Salesforce.
        2. Click **Save & test connection**.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Reference">
    ## Verify Your Setup

    <CodeGroup>
      ```bash Client Credentials Flow theme={null}
      curl -X POST https://YOUR-DOMAIN.my.salesforce.com/services/oauth2/token \
        -d "grant_type=client_credentials" \
        -d "client_id=YOUR_CLIENT_ID" \
        -d "client_secret=YOUR_CLIENT_SECRET"
      ```

      ```bash Test API Access theme={null}
      curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
        "https://YOUR-DOMAIN.my.salesforce.com/services/data/v62.0/query?q=SELECT+Id,Name+FROM+User+LIMIT+5"
      ```
    </CodeGroup>

    <Info>
      Parable's connector posts to your **My Domain URL** (`https://your-org.my.salesforce.com/services/oauth2/token`). Make sure My Domain is enabled and that you have provided the correct subdomain to Parable. (Salesforce also supports `login.salesforce.com` for this flow, but Parable does not use it.)
    </Info>

    <Check>
      **Success!** If you received a `200 OK` response with valid data, your credentials are configured correctly. You can now proceed to configure this connector in Parable.
    </Check>

    <Tip>
      Paste **Consumer Key** and **Consumer Secret** into the Parable connector form, complete OAuth if prompted, then click **Save & test connection**.
    </Tip>

    <Tip>
      **Rate Limits:** {platform_1} enforces rate limits of **{limit_0}**.

      Parable handles rate limiting automatically with exponential backoff, but initial syncs of large datasets may take longer due to these limits.
    </Tip>

    ## Troubleshooting

    | Error                    | Meaning                             | Solution                                         |
    | ------------------------ | ----------------------------------- | ------------------------------------------------ |
    | `INVALID_CLIENT_ID`      | Wrong Consumer Key                  | Verify Client ID from Connected App              |
    | `INVALID_CLIENT`         | Client credentials flow not enabled | Enable "Client Credentials Flow" in app policies |
    | `INACTIVE_USER`          | Run As user deactivated             | Ensure the Run As integration user is active     |
    | `API_CURRENTLY_DISABLED` | API not enabled                     | Contact Salesforce admin to enable API           |

    <Accordion title="Common Issues">
      ### "Connected App not yet available"

      Newly created Connected Apps can take up to 10 minutes to become active. Wait and retry.

      ### "unsupported\_grant\_type"

      Parable posts to your **My Domain URL** (`https://your-org.my.salesforce.com/services/oauth2/token`). Verify My Domain is enabled on your org and that you provided the correct subdomain to Parable. (Salesforce also supports `login.salesforce.com` for this flow, but Parable does not use it.)

      ### IP restrictions blocking access

      Either add your server's IP to the trusted ranges or set IP Relaxation appropriately.
    </Accordion>

    ## Additional Resources

    <CardGroup cols={2}>
      <Card title="Salesforce REST API" icon="book" href="https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/">
        Official REST API documentation
      </Card>

      <Card title="Client Credentials Flow" icon="key" href="https://help.salesforce.com/s/articleView?id=xcloud.remoteaccess_oauth_client_credentials_flow.htm">
        OAuth 2.0 Client Credentials setup guide
      </Card>
    </CardGroup>
  </Tab>
</Tabs>