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

# Connect Salesforce

> Connect your Salesforce org to Brilo from the app store, so your agent can look up and update the contacts and records your team keeps there.

Connecting Salesforce takes about ten minutes and happens in two places: you create an app inside
Salesforce, then paste the values it gives you into the Brilo app store. Brilo checks the details
with Salesforce before saving them, so you know it worked before you leave the screen.

## Before you start

* **Administrator access** to the Salesforce org you want to connect.
* **An integration user** with the **API Enabled** permission and read access to Contacts. On
  Enterprise Edition, Salesforce recommends an **API Only User**. Most teams use a dedicated
  integration user rather than a person's own login.
* Your **My Domain** URL. In Salesforce: **Setup**, then **Company Settings**, then **My Domain**,
  then **Current My Domain URL**. It looks like `https://acme.my.salesforce.com`.
* **Access to the App Store** in your Brilo dashboard. See
  [Plans and what they include](/supported/plans).

## Steps

<Warning>
  Before you change anything in Salesforce, open the **App Store** in your Brilo dashboard and check
  that **Salesforce** is listed. Salesforce is switched on for each workspace, so if you cannot see
  it, contact [support@brilo.ai](mailto:support@brilo.ai) and ask for it to be turned on before you
  go further.
</Warning>

<Steps>
  <Step title="Create an External Client App">
    In Salesforce, go to **Setup**, type `External` in the Quick Find box, and open **External
    Client App Manager**. Click **New External Client App** and fill in the basics.

    | Field | What to enter |
    | - | - |
    | External Client App Name | `Brilo` |
    | API Name | fills in automatically |
    | Contact Email | your admin email |
    | Distribution State | **Local** |

    <Note>
      **Local** is correct. It means the app stays inside your own org, which is what you want.
    </Note>
  </Step>

  <Step title="Turn on OAuth and add the callback URL">
    Expand **API (Enable OAuth Settings)** and tick **Enable OAuth**.

    For **Callback URL**, enter:

    ```
    https://api.brilo.ai/v1/oauth-callback/salesforce
    ```

    <Note>
      Brilo never actually sends you to that address. Salesforce refuses to save an app with an empty
      Callback URL, so it has to be filled in.
    </Note>

    For **OAuth Scopes**, move across only **Manage user data via APIs (api)**. Leave
    `refresh_token` and `offline_access` alone, because Salesforce ignores them for the connection
    type Brilo uses.
  </Step>

  <Step title="Enable the Client Credentials Flow">
    Under **Flow Enablement**, tick **Enable Client Credentials Flow**, then click **Create**.

    Salesforce can take up to 30 minutes to make a new app available, though it is usually much
    faster.
  </Step>

  <Step title="Copy the Consumer Key and Secret">
    Open your new app, go to the **Settings** tab, expand **OAuth Settings**, and click **Consumer
    Key and Secret**. Copy both. You will paste them into Brilo in step 7.
  </Step>

  <Step title="Set the Run As user">
    From the actions list for your app, choose **Edit Policies**. This is a different screen from
    Edit Settings, and skipping it is the most common setup mistake.

    Under **OAuth Policies**, tick **Enable Client Credentials Flow** again here, enter your
    integration user's **username** in **Run As**, and save. The username looks like an email
    address.

    <Note>
      Step 3 tells Salesforce the app is capable of this flow. This step tells Salesforce your org
      permits it, and which user Brilo acts as. Both are required.
    </Note>
  </Step>

  <Step title="Relax IP restrictions, if your org uses them">
    Still on the **Policies** tab, if your org restricts logins by IP range, set **IP Relaxation**
    to **Relax IP restrictions**.

    Skip this step if your org does not use IP restrictions.
  </Step>

  <Step title="Connect in Brilo">
    In your Brilo dashboard, open the **App Store**, choose **Salesforce**, and click **Connect**.

    | Field | Where it comes from |
    | - | - |
    | Connection name | Optional. A name you will recognise in the app store |
    | Instance URL | Your My Domain URL from Before you start |
    | Consumer Key | Step 4 |
    | Consumer Secret | Step 4 |

    Click **Continue**, then **Test connection**. Brilo checks the details with Salesforce before
    saving them. When the test passes, click **Install App**.
  </Step>
</Steps>

## You will know it worked when

* The test passes and the **Install App** button becomes available.
* Brilo shows **Successfully connected your Salesforce account!** with an **Add to an agent**
  button.
* A Salesforce action added to your agent runs on a test call. See
  [Update your CRM](/actions/update-your-crm).

## What you can do once connected

Each item below is an action you add to an agent on its **Actions** tab, and it runs as the Run As
user you set in step 5. Add only the ones that agent needs. The actions fall into five groups.

| Group | Actions |
| - | - |
| Create | Create a contact, Create a lead, Create an account, Create an opportunity, Create a support case, Create a task, Create a note, Create a calendar event, Create a campaign, Add a comment to a case, Add a lead to a campaign, Add a contact to a campaign |
| Update | Update a contact, Update an account, Update an opportunity, Update an email template |
| Look up | Look up a case by Id, Look up a user by Id, Look up records by Id, Search one object by text, Find knowledge articles, List comments on a case, List emails on a case, List email templates |
| Communicate | Post to a Chatter feed, Send an email |
| Any object, custom ones included | Create Record, Update Record, Upsert Record, Get Record, SOQL Query, Search Records, Describe Object |

For setups that use these actions, see [Update your CRM](/actions/update-your-crm) and
[Qualify leads on the call](/recipes/lead-qualification).

## If it did not work

Brilo tells you which of these it was.

| What Brilo says | What to change |
| - | - |
| That is not your Salesforce address | Use your My Domain URL, not the page you sign in at. It ends in `.my.salesforce.com` |
| Salesforce did not recognise this Consumer Key | Copy the Consumer Key again from step 4 |
| Salesforce did not accept this Consumer Secret | Copy the Consumer Secret again from step 4 |
| Salesforce has not enabled this flow yet | Step 5. Use **Edit Policies**, not Edit Settings, and set Run As |
| Salesforce refused the sign in | Your Run As user is empty, inactive, or missing API Enabled. Or your org restricts IP ranges, see step 6 |
| Signed in, but we cannot read your contacts | Add the **Manage user data via APIs (api)** scope in step 2, and give the Run As user read access to Contact |
| Your Salesforce org has used its daily API limit | Nothing is wrong with your details. Wait for the limit to reset, which takes up to 24 hours, then test again |
| This app is already connected | A workspace has one Salesforce connection. Remove the existing one from the Salesforce page in your app store, then connect again |

If the app was created less than 30 minutes ago, wait and try again before changing anything.
Salesforce takes time to make a new app available.

Anything else: [An action did not run](/actions/an-action-didnt-run).

## FAQ

<AccordionGroup>
  <Accordion title="Does Brilo work with Salesforce?">
    Yes. Connect your Salesforce org from the app store using the steps on this page, and your agent
    can work from the contacts and records your team already keeps there. Setup takes about ten
    minutes and needs administrator access to Salesforce.
  </Accordion>

  <Accordion title="Do I need a paid Salesforce plan?">
    You need a Salesforce edition that allows API access, which rules out the entry level editions.
    Enterprise Edition and above are fine. Check with your Salesforce administrator if you are not
    sure which edition your org is on, before you start the setup.
  </Accordion>

  <Accordion title="Do I need a developer to connect Salesforce?">
    No, but you do need a Salesforce administrator. Every step happens in the Salesforce Setup
    screens and the Brilo app store, and nothing has to be written or installed. Budget about ten
    minutes for the whole setup. See
    [Do I need a developer](/start/do-i-need-a-developer).
  </Accordion>

  <Accordion title="What does Brilo read and write in Salesforce?">
    Brilo acts as the integration user you set under Run As, so it can do exactly what that user can
    do and nothing more. Give that user the minimum access your actions need, which for most setups
    is read access to Contacts.
  </Accordion>

  <Accordion title="Why does my Salesforce connection keep failing?">
    The usual causes are a Run As user missing from **Edit Policies** in step 5, and an app created
    less than 30 minutes ago that Salesforce has not made available yet. Both show up at the test
    stage, before anything is saved. Work through the table above, which names what Brilo reported
    and what to change.
  </Accordion>

  <Accordion title="Can I connect two Salesforce orgs?">
    No. A workspace holds one Salesforce connection. To use a different org, remove the existing
    connection from the Salesforce page in your app store, then connect the other org with the steps
    on this page. Actions you already added keep their settings, so check each one points at what
    the new org expects.
  </Accordion>

  <Accordion title="What happens to my data if I disconnect Salesforce?">
    Disconnecting removes the connection from your workspace. Everything already written into
    Salesforce stays, because those records belong to Salesforce. To cut off access completely,
    also delete the External Client App in Salesforce, which retires its Consumer Key and Secret so
    they can never be used again.
  </Accordion>

  <Accordion title="Are my Salesforce keys safe in Brilo?">
    Your Consumer Key and Secret are encrypted before they are stored and are only ever used to
    reach your own org. Brilo never asks for a Salesforce password. It requests a fresh access token
    whenever Salesforce stops accepting the old one, so you never have to sign in again.
  </Accordion>
</AccordionGroup>

## Related

* [Integrations](/integrations) for connecting anything else
* [Connect Vagaro](/integrations/vagaro) for the other app with its own setup
* [Update your CRM](/actions/update-your-crm) for what to add after connecting
* [Lead qualification](/recipes/lead-qualification) for a setup that uses a CRM
* [Supported integrations](/supported/integrations) for the current list of tools
* [An action did not run](/actions/an-action-didnt-run) when a connection misbehaves


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