> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://katalyz.crisp.help/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# Connecting Salesforce

Connect your Salesforce org to Katalyz to sync rooms, deals (opportunities), accounts, contacts, and activity.

> ⚠️ Requires org role **Admin**.

## Before you start

You'll need:
- **Salesforce admin access** (to install and authorize the Katalyz app).
- A Salesforce org with **access to Apex callouts** enabled — this is the one hard requirement.

## Full setup procedure

> ⚠️ **Critical — both sides must use the same email.** The **Salesforce admin** account installing the integration and the corresponding **Katalyz** account must share the **exact same email address**. Without this, the two orgs can't be paired.

### 1. Activate the integration on the Katalyz side

1. Go to **Settings → Integrations**.
2. Find **Salesforce** in the list, click **Connect**.
3. You're redirected to Salesforce for OAuth — sign in with an admin account and authorize the connection.
4. At this point, Katalyz captures your Salesforce **Org ID** and links it to your workspace.

### 2. Install the Salesforce package

Install the Katalyz managed package in your Salesforce org:

- Install URL: `https://login.salesforce.com/packaging/installPackage.apexp?p0=04tJ7000000szEFIAY`
- **Package key**: `katalyzsalesforce`
- Choose **Install for all users**.

### 3. Assign the permission set

Once the package is installed, assign the **Katalyz** permission set to the users who need to interact with the integration:

1. **Setup → Permission Sets → Katalyz**
2. Click **Manage assignments**
3. **Add assignment** → select the relevant users → **Next** → **Assign**

### 4. Fill in the Custom Settings

The integration needs your **Katalyz API key** and **tenant**:

1. **Setup → Custom Settings → Katalyz Org Credentials settings**
2. Click **Manage**, then **New**
3. Enter:
   - **API key** — customer-specific key (ask your Katalyz contact; one per customer)
   - **Tenant** — tenant identifier provided by Katalyz

### 5. Add the Katalyz component to the Opportunity page (Lightning)

So the Katalyz rooms list shows up on every opportunity:

1. **Setup → Object Manager → Opportunity → Lightning Record Pages**
2. Open **Opportunity Record Page** → **Edit**
3. In the components search box, type **Katalyz Dealrooms List**
4. **Drag-and-drop** the component to the desired location on the page → **Save**
5. **Activation** → **Assign as Org Default** (so the component is shown by default on every opportunity)

### 6. Add the "Katalyz Dealroom Activities" related list

To surface Katalyz activity in the opportunity timeline:

1. **Setup → Object Manager → Opportunity → Page Layouts**
2. Open the active layout → **Related Lists** section
3. Add **Katalyz Dealroom Activities** → save

### 7. Activate `client_id` by creating a first room

To complete the pairing, create a Katalyz room **from Salesforce** (from any opportunity, via the Katalyz component you just added). This first creation activates the `client_id` on the Katalyz side and finalizes the link.

### 8. User-level connection

Once the Salesforce integration is enabled at the workspace level, **each user also has to authorize Salesforce from their own profile** for the integration to work fully for them — their own actions (creating a room from an opportunity, updating a field, back-sync) then authenticate with their own Salesforce permissions.

1. Each user opens **their profile**.
2. They click **Sign in with Salesforce** and authorize the connection.
3. From then on, their actions use their own Salesforce token.

Without this step, the org-level integration is still healthy but that user's individual actions won't sync. See [My CRM isn't syncing](https://katalyz.crisp.help/en/article/my-crm-isnt-syncing-hubspot-salesforce-16192yz/) for the full two-level model.

## What Katalyz requests access to

The Salesforce OAuth screen lists the exact scopes Katalyz requests:

| Scope | Why Katalyz asks for it |
|---|---|
| `api` | Allows Katalyz to use Salesforce APIs to read and update CRM records — Accounts, Contacts, Opportunities, Tasks, custom fields, files, and related CRM metadata needed for sync. |
| `refresh_token` | Allows Katalyz to refresh access without asking the user to reconnect every time a Salesforce access token expires, so background sync jobs can keep running. |

## After connecting

Field mapping for Salesforce uses **the same UI as HubSpot field mapping** — same "Synced fields" surface, same workflow. The one difference: there is **no "Import from CRM"** action on the Salesforce side (unlike HubSpot). See [CRM field mapping & sync](https://katalyz.crisp.help/en/article/crm-field-mapping-sync-hubspot-salesforce-fzz4c/) for the UI; everything described there applies to Salesforce too.

## Disconnecting

**Settings → Integrations → Salesforce → Disconnect**.

## Related articles
- [Salesforce: syncing rooms with opportunities, accounts and contacts](https://katalyz.crisp.help/en/article/salesforce-syncing-rooms-with-opportunities-accounts-and-contacts-14o5upy/)
- [Connecting HubSpot](https://katalyz.crisp.help/en/article/connecting-hubspot-160gs96/)