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

# Install and setup

> Install the BotShield managed package, assign permission sets, and connect your BotShield Console keys.

This takes about 15 minutes. When you're done, the **BotShield → Setup** tab shows a green health checklist and both rails are ready to use.

<Note>
  You'll need your **BotShield Console API key** (from [console.botshield.ai](https://console.botshield.ai/console) → **Settings → API Keys**). Keep it handy for step 3.
</Note>

## 1. Install the package

Install **BotShield** from AgentExchange into your org (production or sandbox). After install, open the **App Launcher** and choose **BotShield** — you'll land on the Home tab with a health pill reading `0/8 ready` until setup is complete.

## 2. Assign permission sets

Assign the permission sets to the users who need them (**Setup → Permission Sets**, or the **People** section of the BotShield Setup tab):

| Permission set | Give it to |
| - | - |
| `BotShield_Admin` | Admins who configure BotShield and see every tab. |
| `BotShield_User` | People who link their BotShield app and are asked to approve actions. |
| `BotShield_Approver` | Users allowed to co-sign sensitive actions (e.g. refunds). |
| `BotShield_Integration` | The integration/run-as user that receives the Console data push. |

## 3. Connect your Console keys

BotShield calls your BotShield Console over **Named Credentials** — no keys are stored in code or metadata.

<Steps>
  <Step title="Set the agent key">
    Go to **Setup → Named Credentials → External Credentials → `BotShield_Agent_Default`**, edit the principal, and paste your Console **agent key** into the credential parameter. This authorizes the Agents Ask rail.
  </Step>

  <Step title="Set the Admin API key (optional)">
    On the `BotShield_Admin_API` External Credential, paste a read-only **Admin API** key. This lets the app sync your deployments and agents automatically. Without it, everything still works — you just add deployments manually.
  </Step>

  <Step title="Choose your environment">
    In the **BotShield Setup** tab, set the environment to **Production** (or **Staging** while you test). This points the widgets and callouts at the matching BotShield hosts.
  </Step>
</Steps>

## 4. Connect the Console and choose what pushes

This is where you tell BotShield to write verifications and resolutions back into your org. In the Console, open **Settings → Integrations** — the list of platforms that receive BotShield Gate results and Agents Ask resolutions — and find the **Salesforce** card. It's two steps: **connect**, then **configure targets**.

<Frame caption="Settings → Integrations — the platforms that receive BotShield Gate results and Agents Ask resolutions.">
  <img src="https://mintcdn.com/botshield-0eb40fde/V-yYCmwfn-enTLcG/images/salesforce/integrations.png?fit=max&auto=format&n=V-yYCmwfn-enTLcG&q=85&s=55f023202ef6e68d42aafa72c8bd5865" alt="BotShield Console Settings → Integrations, showing the Salesforce card" width="2000" height="1689" data-path="images/salesforce/integrations.png" />
</Frame>

### 4a. Connect your org

Click **Connection** on the Salesforce card. BotShield authenticates to your org with **Connected App credentials (OAuth client-credentials flow)** — one org per environment.

<Steps>
  <Step title="Pick the environment">
    Choose the **Development** or **Production** tab. Development receives your sandbox / Developer Edition events; Production, your production org.
  </Step>

  <Step title="Enter the Connected App credentials">
    Paste your org's **Instance URL**, **Consumer Key**, and **Consumer Secret** — from the Connected App (External Client App) in your Salesforce org. The BotShield **Setup** tab's *Data push* section walks you through creating it: OAuth enabled, `api` scope, **client-credentials flow**, Run-As an integration user holding the `BotShield_Integration` permission set. Secrets are stored server-side and never shown again.
  </Step>

  <Step title="Test and save">
    Click **Test Connection**. A green result means the Console can reach your org through the Run-As user. **Save**, then flip **Enable Salesforce Integration** on.
  </Step>
</Steps>

<Frame caption="Salesforce Connection — Connected App credentials (OAuth client-credentials), per environment.">
  <img src="https://mintcdn.com/botshield-0eb40fde/V-yYCmwfn-enTLcG/images/salesforce/connection.png?fit=max&auto=format&n=V-yYCmwfn-enTLcG&q=85&s=e1c0cc1ea78d70fec8a59cf6ea808ca4" alt="Salesforce Connection modal with Instance URL, Consumer Key and Secret, and Test Connection" width="946" height="1448" data-path="images/salesforce/connection.png" />
</Frame>

### 4b. Choose which Gates and Agents push

Back on the Salesforce card, click **Configure**. You'll see a two-column picker — **Available** on the left, **Pushing to Salesforce** on the right — with the same Development / Production toggle.

Move the deployments and agents you want writing into your org to the right-hand column:

* **BotShield Gates** write verification outcomes to `BotShield_Gate__c`.
* **Agents Ask agents** write approval outcomes to `BotShield_Resolution__c`.

Changes apply immediately — a target starts (or stops) pushing on its next terminal event.

<Frame caption="Configure — move Gates and Agents into “Pushing to Salesforce.”">
  <img src="https://mintcdn.com/botshield-0eb40fde/V-yYCmwfn-enTLcG/images/salesforce/configure.png?fit=max&auto=format&n=V-yYCmwfn-enTLcG&q=85&s=a522250856512851425030f35e92a5ba" alt="Salesforce Enabled Deployments & Agents dual-list picker" width="1398" height="1198" data-path="images/salesforce/configure.png" />
</Frame>

<Warning>
  The Salesforce integration is **one org per environment**. Point Production at your production org and Development at your sandbox — don't cross them, or pushed records land in the wrong place.
</Warning>

<Note>
  The managed-package **push** requires the BotShield AgentExchange package installed in the org. You can connect and pick targets now; pushes start once the package is installed.
</Note>

## 5. Verify

Open **BotShield → Setup** and click **Re-check**. Each row turns green as its prerequisite is met — keys set, run-as user assigned, last row received. When the health pill reads all-ready, you're set.

## Next steps

<CardGroup cols={2}>
  <Card title="Human Verification on Experience Cloud" icon="user-check" href="/integrations/salesforce/human-verification-experience-cloud">
    Gate an Experience Cloud checkout or form.
  </Card>

  <Card title="Agents Ask in Agentforce" icon="robot" href="/integrations/salesforce/agents-ask-agentforce">
    Require human confirmation for agent actions.
  </Card>

  <Card title="Agents Ask in Flow" icon="diagram-project" href="/integrations/salesforce/flow-pause-resume">
    Pause a Flow for a human approval.
  </Card>

  <Card title="Link with BotShield" icon="link" href="/integrations/salesforce/overview">
    Pair the BotShield app so people can be asked.
  </Card>
</CardGroup>