# Install the Suger App

Install the Suger managed package from Salesforce AppExchange and establish a live, two-way connection between Salesforce and Suger.

---

## Overview

By the end of this guide, you will have:

- The Suger package installed in your Salesforce org
- A dedicated Integration User set up for the connection
- A live, verified two-way connection between Salesforce and Suger

You only need to complete this setup once.

:::warning
**Do not use a personal Salesforce user account for the integration.** You will create a dedicated Integration User in Step 2. Using a personal account means the connection breaks if that person leaves or changes roles.
:::

---

## Prerequisites

Make sure you have the following before you begin:

- **Salesforce Administrator access** — required to install packages and create users.
- **A Suger account** — sign in at [console.suger.io](https://console.suger.io/).
- **Your Suger Organization ID** — found in [Settings → Organization & Users](https://console.suger.io/settings?tab=organization).
- **A Suger API Key** — generated in [Settings → API Client](https://console.suger.io/settings?tab=api_client).

---

## Step 1: Install the Suger package from AppExchange

This installs the Suger App into your Salesforce org.

1. Go to the [Suger listing on Salesforce AppExchange](https://appexchange.salesforce.com/appxListingDetail?listingId=a0N3u00000RMskLEAT).
2. Click **Get it Now**.
3. Log in with your Salesforce Admin account when prompted.
4. Choose where to install:
   - Select **Production** for your live org.
   - Select **Sandbox** if you are testing first.
5. When asked who to install for, select one of the following:
   - **Admins Only** — recommended to start; you can expand access later.
   - **All Users** — installs for everyone immediately.
   - **Specific Profiles** — installs only for selected profiles.
6. Click **Install** and wait for the confirmation email from Salesforce.

:::note
The confirmation email may take a few minutes to arrive. Do not click **Install** again — Salesforce is processing the request in the background.
:::

---

## Step 2: Create a dedicated Integration User

The Integration User is a special Salesforce account that Suger uses to read and write data in your org. It is not a person — it is a service account.

### Choose a license type

Pick the right license before creating the user.

| License type | When to use |
| --- | --- |
| Salesforce Integration License | Use this in most cases. It is free and designed for API-only connections. The user cannot log in via the Salesforce UI. |
| Salesforce License (standard) | Use this only if your field mapping involves Quote objects — either a standard Salesforce Quote or a CPQ Quote. |

:::note
If you are using Salesforce CPQ (also called SBQQ), you also need to assign a CPQ license to this user on top of the standard Salesforce License.
:::

### Create the user

1. In Salesforce, click the **Gear icon (⚙️)** → **Setup**.
2. In the **Quick Find** box, type `Users` and select **Users**.
3. Click **New User**.
4. Fill in the required fields:
   - Enter a recognizable name like `Suger Integration`.
   - Enter a valid email address — Salesforce will send an activation link here.
   - Set the **License** to whichever option you chose above.
5. If you selected **Salesforce Integration License**, set the **Profile** to **Salesforce API Only System Integrations**.
6. Click **Save**, then activate the user via the email Salesforce sends.

### Assign permission sets to the Integration User

Permission sets control what data Suger can access in your org. You need to assign two things.

#### First — assign the Suger Integrator permission set

1. Go to **Setup** → **Permission Sets**.
2. Find and open the permission set that matches your license type:
   - **Salesforce Integration License** → assign **Suger Integrator (Salesforce Integration License)**.
   - **Salesforce License** → assign **Suger Integrator**.
3. Click **Manage Assignments** → **Add Assignments** → select your Integration User → **Assign**.

#### Second — create a custom permission set for object access

Suger also needs read access to standard Salesforce objects like Account, Contact, and Opportunity. Create a permission set for this manually.

1. Go to **Setup** → **Permission Sets** → **New**.
2. Name it something like `Suger Integration Object Access`.
3. Set the license to match your Integration User:
   - **Salesforce Integration License** → select **Salesforce API Integration** _(not "Salesforce Integration" — these are different)_.
   - **Salesforce License** → leave the license field as default.
4. Inside the permission set, grant **Read** and **View All** access on:
   - Account
   - Contact
   - Opportunity
   - Any other objects or fields you plan to use in your Suger field mapping.
5. If you are using standard Salesforce Quotes, also grant **Read** access on Product2, Pricebook2, and Quote.
6. Save the permission set, then assign it to your Integration User using the same steps above.

:::note
For a full reference of the Suger permission sets available in the package, see [Permission Sets](/salesforce-app/salesforce-app-permission-sets).
:::

---

## Step 3: Configure Salesforce to talk to Suger

This step tells Salesforce where Suger is and how to authenticate with it. You do this from inside the Suger App in Salesforce.

1. In Salesforce, click the **App Launcher** (the nine-dot grid icon in the top-left) and search for **Suger**.
2. Open the Suger app and navigate to **Settings**.
3. Fill in the following fields:

   | Field | What to enter |
   | --- | --- |
   | Organization ID | Your Suger Org ID from [Settings → Organization & Users](https://console.suger.io/settings?tab=organization). |
   | API Endpoint | `https://api.suger.cloud` |
   | API Key | Your Suger API Key from [Settings → API Client](https://console.suger.io/settings?tab=api_client). |

4. Click **Save**.

:::warning
**Double-check your API Key for trailing spaces.** A space at the end is invisible but will cause authentication to fail.
:::

---

## Step 4: Connect Suger to Salesforce

This step goes in the other direction — it authorizes Suger to read and write data in your Salesforce org using the Integration User you created in Step 2.

1. Go to [Suger Console](https://console.suger.io) → **Settings** → **Integrations** → **Salesforce**.
2. Click **Connect Now**.
3. Enter your **Salesforce Subdomain** — for example, `acme.my.salesforce.com`.
   - Find this in Salesforce at **Setup** → **Company Settings** → **My Domain**.
4. If you are connecting to a Sandbox org, check the **Sandbox** checkbox.
5. Click **Create**.
6. Salesforce will prompt you to log in — sign in as the **Integration User** you created in Step 2, not your personal admin account.
7. After logging in, return to Suger Console and click **Verify** to confirm the connection is live.

:::note
If you need to reconnect later — for example, after changing OAuth policy settings in Salesforce — return to this screen and click **Connect Now** again.
:::

For more detail on the integration configuration and mapping options, see the [Salesforce Integration Setup Guide](/integrations/salesforce).

---

## Troubleshooting common issues

| Issue | Possible cause | Resolution |
| --- | --- | --- |
| API Key authentication fails | Trailing space in the API Key field | Delete and re-enter the API Key, making sure there are no spaces before or after it. |
| "Not approved for access" error during OAuth | Integration User's profile is not listed under Permitted Users in the Suger External Client App | Go to **Setup** → **External Client App Manager** → **Suger** → **Policies** and add the Integration User's profile or permission set under Selected Profiles/Permission Sets. |
| Suger buttons not visible after connection | User has not been assigned the correct Suger permission set | Go to **Setup** → **Permission Sets** and assign the appropriate [Suger permission set](/salesforce-app/salesforce-app-permission-sets) to the user. |
| Users can see buttons they should not | Extra custom permissions were auto-enabled when the package was installed | Go to the user's profile → **Custom Permissions** and uncheck any Suger permissions that should not apply. |
| Connection works but data is not syncing | Integration User lacks Read/View All access on required objects | Review the custom object permission set you created in Step 2 and add any missing object or field access. |
| Salesforce Integration License user cannot log in | This is expected — the Salesforce Integration License is API-only by design | Use a standard Salesforce License if your team needs the Integration User to log in via the UI. |

---

## Frequently Asked Questions

**Do I need to reinstall the package every time Suger releases an update?**

No. Suger pushes managed package updates automatically. You do not need to reinstall from AppExchange to get new features.

**Can I use my personal Salesforce Admin account as the Integration User?**

You can, but it is not recommended. If your account is deactivated, renamed, or its password changes, the Suger connection breaks. A dedicated Integration User keeps the connection stable regardless of staff changes.

**Can I connect Suger to both a Production org and a Sandbox at the same time?**

Yes. In Suger Console → **Settings**, you can add additional environments. Check the **Sandbox** checkbox when connecting a sandbox org.

**What is the difference between the Suger Integrator permission set and the custom object permission set I created in Step 2?**

The **Suger Integrator** permission set gives the Integration User access to Suger's custom objects and features. The custom object permission set you created gives Suger access to your standard Salesforce objects like Account and Opportunity. Both are required.

**What happens if I click "Connect Now" again on an existing connection?**

It re-initiates the OAuth flow. Use this if the connection breaks, or if you have updated OAuth policy settings in Salesforce and need to reauthorize.