# Connect

Connect a Salesforce production or sandbox org to a profile through OAuth, from the dashboard or with the connect API.

## Before you start

A Salesforce admin installs the Zernio package in the org first. Zernio's sign-in app ships inside it, so connecting an org without the package fails. A sandbox needs its own install.

## Install the Zernio package

1. Open the install link signed in as a Salesforce admin: [production or Developer Edition](https://login.salesforce.com/packaging/installPackage.apexp?p0=04tfj000000llzZAAQ), or [sandbox](https://test.salesforce.com/packaging/installPackage.apexp?p0=04tfj000000llzZAAQ).
2. Choose **Install for Admins Only**, and approve third-party access to `zernio.com` when asked.
3. In **Setup > Permission Sets**, assign **Zernio Admin** and **Zernio User** to yourself, and **Zernio User** to everyone who will send from Salesforce.

Sending from Salesforce also needs an API key on the **Zernio Setup** tab; see [Send templates from Salesforce](/platforms/salesforce/send-templates).

## Limit who can connect

By default any user of the org can approve Zernio. To limit it, open **Setup > External Client App Manager > Zernio > Policies** and set **Permitted Users** to admin-approved users with a permission set.

If the org restricts login IP ranges, set **IP Relaxation** to **Relax IP restrictions** so Zernio can renew its access. Orgs with API Access Control on must allow the Zernio app there.

## Connect from the dashboard

1. Sign in to [Zernio](https://zernio.com/dashboard/connections) (a free account works) and open **Connections**.
2. Click **Connect an account**, pick the profile, and choose **Salesforce** under **CRM**.
3. If the org does not have the package yet, choose **Install the Zernio package** (or **in a sandbox**) and finish the install in Salesforce.
4. Choose **Connect a production org** or **Connect a sandbox**, sign in to Salesforce and allow access.
5. Back in Zernio, the org shows on the profile. Contact creation, logging and delivery status are on, and new people become Leads.

## Connect a Salesforce org

Request the authorization link for a profile, then send the user to `authUrl`:

```bash
curl "https://zernio.com/api/v1/connect/salesforce?profileId=PROFILE_ID&redirect_url=https://example.com/done" \
  -H "Authorization: Bearer $ZERNIO_API_KEY"
```

```json
{ "authUrl": "https://login.salesforce.com/services/oauth2/authorize?client_id=…", "state": "…" }
```

The user signs in and allows access. Salesforce returns them to Zernio, which saves the account with the org's instance URL and redirects to `redirect_url` (or the dashboard) with `connected=salesforce`, `profileId`, `accountId` and `username`.

## Connect a sandbox

Add `environment=sandbox` and the user signs in through `test.salesforce.com`:

```bash
curl "https://zernio.com/api/v1/connect/salesforce?profileId=PROFILE_ID&environment=sandbox" \
  -H "Authorization: Bearer $ZERNIO_API_KEY"
```

A sandbox is its own org: install the package in it and connect it to its own profile. After a sandbox refresh, disconnect the old sandbox account, then connect again.

## Disconnect

On **Connections**, click **Disconnect** on the Salesforce account, or call `DELETE /v1/accounts/{accountId}`. Zernio stops syncing and revokes its access token.

What Zernio already wrote stays in Salesforce: the Leads and Contacts it created and their Tasks are not deleted. Nothing new syncs until you connect again, and messages from the gap are not backfilled.

## How it behaves

- A profile holds one org. Reconnecting the same org refreshes the account in place and keeps its settings.
- Access renews by itself. If a Salesforce admin revokes Zernio's access, the account is marked disconnected the next time a message syncs.

## If it fails

| Error | Cause | Fix |
|-------|-------|-----|
| `salesforce_access_denied` on the redirect | The user declined access | Start the connect again and allow access. |
| `salesforce_invalid_state` on the redirect | The link expired or was already used | Request a fresh `authUrl`. |
| `salesforce_connection_failed` on the redirect | Salesforce refused the code exchange, or the org could not be read | Start the connect again; check the user has API access. |
| `salesforce_package_not_installed` on the redirect | Salesforce refused the sign-in because the Zernio package is not installed in this org | [Install the package](#install-the-zernio-package), then connect again. |
| `salesforce_profile_has_org` on the redirect | The profile already has a different org connected | Disconnect it first, or connect this org to another profile. |
| `salesforce_auth_failed` on the redirect | Salesforce returned without an authorization code | Start the connect again. |
| `503` on `GET /v1/connect/salesforce` | Salesforce is not configured on this Zernio environment | Contact support. |

## Related

- [Get Salesforce connect URL](/connect/get-salesforce-connect-url)
- [Settings](/platforms/salesforce/settings)
- [Inbox sync](/platforms/salesforce/sync)