> For the complete documentation index, see [llms.txt](https://docs.pharos.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pharos.ai/configuration-guide/connected-orgs.md).

# Connected Orgs

Set up Connected Orgs: add each org, authenticate the connection, filter what's sent, and fix common connection problems.

The **Connected Orgs** screen manages how your Salesforce environments relate to one another. This page covers setting a connection up: adding each org, authenticating, filtering what's sent, and fixing common problems.

A connection between two orgs is set up from both ends, in a fixed order: the receiving org (the target) first, then the sending org (the source), which then signs in to the target. For why it works this way, what happens behind the scenes, and the use cases it supports, see [Connected Orgs](https://docs.pharos.ai/platform-overview/pharos-platform-architecture/logs/log-ingestion-methods/connected-orgs.md) in Platform Architecture.

{% hint style="success" %}
**New to Connected Orgs?** The [Broadcast Logs to a Hub Org tutorial](https://docs.pharos.ai/configuration-guide/connected-orgs/connected-orgs-broadcast-tutorial.md) walks through a complete setup, with a video, and checks that a real error arrives on the hub.
{% endhint %}

***

## Accessing Connected Orgs

Navigate to **Pharos App → Pharos Admin → Connected Orgs**. The page lists your connected orgs and their configuration, with a **New** button to add one.

![Connected Orgs page — Single/Multi Org explanation, Passthrough Mode toggle, and a table of connected orgs with Org Name, Org ID, Type, Description, Filter Criteria, and Data Direction](https://4264222071-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fdl9tmJ56lvwg5XY63QYr%2Fuploads%2Fgit-blob-d84b24379a3835564d98da6d6d34d0686acadece%2Fconnected-orgs-overview.png?alt=media)

### Single Org vs. Multi Org

* **Single Org** — logs stay on the org that produces them. This is the simplest and most common setup, and needs only one connected org: a **"loopback"** connection to the org itself.
* **Multi Org** — logs are collected on one host org from other orgs. Add a connected org for each org you send to or receive from.

**Passthrough Mode** (the toggle on this page) makes Pharos *stop retaining log records locally* and instead stream them to another Pharos instance. If the connection to that instance is invalid, Pharos keeps logs on this org until you re-authenticate. Those logs stay here: they aren't sent to the target afterwards. See [Broadcast and Passthrough](https://docs.pharos.ai/platform-overview/pharos-platform-architecture/logs/log-ingestion-methods/connected-orgs.md#broadcast-and-passthrough).

Each row in the table shows the org **Name**, **Org ID**, **Type**, **Description**, any **Filter Criteria**, and its **Data Direction** (for example, *Send to this org*).

***

## Adding a Connected Org

Click **New** and complete the form. At minimum you provide a **Name**, **Description**, **Org Type** (Production or Sandbox), the **Login URL**, a **Data Direction**, and the target **Org Id**.

![New Connected Org form — Name, Description, Org Type, Login URL, Data Direction, Org Id, and an Enable Filters toggle](https://4264222071-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fdl9tmJ56lvwg5XY63QYr%2Fuploads%2Fgit-blob-618e794aaf7afd3e2a3ba438ec85ef05be319c39%2Fconnected-orgs-new-form.png?alt=media)

**Data Direction** defines each side of the connection:

* **Send to this org** — configured on the *source* org, pointing at the target that receives the logs.
* **Receive from this org** — configured on the *target* org, naming the source it accepts logs from.

Establishing a connection is a two-sided setup: the source org sends, and the target org receives. Each record's **Org Id** is the *other* org's Organization ID (find it in **Setup → Company Information**).

**Save the record before you authenticate.** **Check** and **Login to Org** work from the saved record.

***

## Authentication

Pharos can authenticate a connection in two ways. A connection to **another org** always uses an External Client App: **Use Client App Authentication** is switched on and can't be turned off. Session login is available only for the org's own loopback connection.

### Session Login (loopback only)

For the loopback connection, Pharos can use your current session. This is the quickest path, but **Session ID authentication fails in many secured orgs**—for example those with API Access Control or API-enabled restrictions, enforced SSO via My Domain without local passwords, Government Cloud, or IP allowlisting. In those environments, use an External Client App instead.

### External Client App

**External Clients are the modern replacement for Connected Apps** and are the preferred choice wherever security is paramount. Enable **Use Client App Authentication** to connect this way.

![Connected Orgs form with Use Client App Authentication enabled and an OAuth Token field with a Check button](https://4264222071-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fdl9tmJ56lvwg5XY63QYr%2Fuploads%2Fgit-blob-97e28c251b4636e614913c7c150fdedfc098609f%2Fconnected-orgs-check.png?alt=media)

Because the external client has to be **created first**, there's a short delay before it becomes usable—and there's no API Pharos can call to confirm readiness. The **Check** button lets you test availability on demand. Until the client is ready, Pharos shows:

![Warning banner reading "External client is not yet available for use, please try again in a few minutes"](https://4264222071-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fdl9tmJ56lvwg5XY63QYr%2Fuploads%2Fgit-blob-802af9d9592e65dcf7951f05e03f11c84451ae6f%2Fconnected-orgs-not-available.png?alt=media)

Once the external client is available, the button becomes **Login to Org**.

![Connected Orgs form showing the OAuth Token field with a Login to Org button, for the Target Org connection](https://4264222071-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fdl9tmJ56lvwg5XY63QYr%2Fuploads%2Fgit-blob-c5f18009115e52a63386c965502dcbf71a9c4170%2Fconnected-orgs-login-to-org.png?alt=media)

Click **Login to Org** and authorize the connection on Salesforce's **Allow Access?** screen.

![Salesforce "Allow Access?" consent screen listing the OAuth scopes the Pharos external client requests](https://4264222071-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fdl9tmJ56lvwg5XY63QYr%2Fuploads%2Fgit-blob-64c8ce6950655b8c1f0b85bd2aabfef599269281%2Fconnected-orgs-allow-access.png?alt=media)

After you allow access, the **OAuth Token** is stored (masked). You can revoke and re-establish it later with **Reset**.

{% hint style="warning" %}
**Don't put Login IP Ranges on the profile of the user you sign in as.** Pharos refreshes the token from Salesforce's servers, which fall outside those ranges, so the refresh fails with `invalid_grant` / `ip restricted` and the connection stops sending.
{% endhint %}

![Saved Target Org connection — Use Client App Authentication on, a masked OAuth Token with a Reset button, and Data Direction set to Send to this org](https://4264222071-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fdl9tmJ56lvwg5XY63QYr%2Fuploads%2Fgit-blob-d3e0b8f3b9325b35d80af9025b6b75f0dfa9bcca%2Fconnected-orgs-target-saved.png?alt=media)

***

## Source and Target

A multi-org connection is defined from both ends. Set them up in this order:

1. On the **target** org, add the source with **Receive from this org**.
2. On the **source** org, add the target with **Send to this org** and save.
3. On the **source** org, authenticate the connection.

The **Mode** field on the receiving side is read-only. It shows *Broadcast Only* unless the target has also signed in to the source, when it shows *Broadcast / Passthrough*.

Only the source authenticates. The target's *Receive from this org* record needs no login.

On the target, each received log shows the receiving record's **Name** in **Organization Name**, and **Broadcast** in **Originated From**. On the source, a log's **Broadcast Status** moves from **Needed** to **Completed** once it's sent.

![Target org's record for the source — Data Direction set to Receive from this org, with Mode set to Broadcast Only](https://4264222071-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fdl9tmJ56lvwg5XY63QYr%2Fuploads%2Fgit-blob-a02e024df8c838b64696fb97ccae307ea752cec4%2Fconnected-orgs-source.png?alt=media)

***

## Filtering What's Sent

You don't have to send every log. Turn on **Enable Filters** to restrict which records a connected org sends—Pharos only sends a log when the filter criteria evaluate to `True`. Criteria are `Field` / `Operator` / `Value` rows (for example, `Category` **Equal** `Apex`), and can reference any field on the Log record.

![Enable Filters toggled on, with a Filter Criteria row set to Category Equal Apex](https://4264222071-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fdl9tmJ56lvwg5XY63QYr%2Fuploads%2Fgit-blob-41562ecc3f2065436c7810efecf3b5d5223aab60%2Fconnected-orgs-filters.png?alt=media)

***

## Troubleshooting

| Issue                                                                                                                                                                                           | Likely cause                                                                                                                                          | Resolution                                                                                                                                                                                                                                                |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Session login won't connect                                                                                                                                                                     | Org restricts Session ID (API Access Control, enforced SSO, Government Cloud)                                                                         | Enable **Use Client App Authentication** and connect with an External Client App                                                                                                                                                                          |
| "External client is not yet available"                                                                                                                                                          | The external client hasn't finished provisioning yet                                                                                                  | Wait a few minutes and press **Check** again                                                                                                                                                                                                              |
| Source logs never get a **Broadcast Status**, or the token was revoked                                                                                                                          | The connection was marked invalid, for example after a failed token refresh                                                                           | Open the connection on the source, use **Reset**, then **Login to Org** again                                                                                                                                                                             |
| *"Connected Org has no refresh token. Log in to this org again from Pharos Connected Orgs."*                                                                                                    | The connection's token was reset and nobody has logged in again                                                                                       | Open the connection on the source and click **Login to Org**                                                                                                                                                                                              |
| In Passthrough Mode, the connection shows **Connection invalid**, or the source's Logs show *"Connected Org not found (PassthroughMode)"* or a log asking you to re-authenticate the connection | The target rejected the token refresh (`invalid_grant`): the refresh token expired or was revoked                                                     | On the **source** org, open the connection, use **Reset**, then **Login to Org**. Until you do, logs stay on the source, and they aren't sent to the target afterwards. If it goes invalid again soon after, check the user's Login IP Ranges (see below) |
| A connection shows **Connection invalid**, and Logs show *"Connected Org was created by an earlier Pharos version and can no longer be authenticated…"*                                         | The connection was created by an earlier Pharos version, such as Pharos 1.x, and the connected app it signed in through can no longer authenticate it | Delete the connection and set it up again. See [Connections from an earlier Pharos version](#connections-from-an-earlier-pharos-version)                                                                                                                  |
| Logs from before the connection never reach the target                                                                                                                                          | Connections don't backfill: only logs that finish processing after the connection is in place are sent                                                | Expected. New logs will flow; older logs stay on the source                                                                                                                                                                                               |
| Logs not arriving at the target                                                                                                                                                                 | Data Direction, Org Ids or filters misconfigured                                                                                                      | Confirm the source is set to *Send to this org* and the target to *Receive from this org*, that each **Org Id** is the *other* org's ID, and review any enabled filters                                                                                   |
| `invalid_grant` / `ip restricted` on the source                                                                                                                                                 | The target user's profile has Login IP Ranges                                                                                                         | Remove the ranges, or connect as a user whose profile has none; then **Reset** and **Login to Org**                                                                                                                                                       |
| *"API is disabled for this User"* for logs written through platform events                                                                                                                      | The platform event trigger runs as the Automated Process user, which can't make API calls                                                             | Set the platform event running user to an admin user (for Triton: **Pharos Admin → Advanced → Triton → Configuration**), then suspend and resume the subscription                                                                                         |

For the Passthrough Mode **Connection invalid** issue above, look for the re-authenticate log in the **source** org's Logs: it can't travel through the broken connection, so Pharos writes it there. Its Summary reads: *"Connected Org token refresh rejected (invalid\_grant). Re-authenticate this connection in Pharos Connected Orgs: the refresh token expired or was revoked."*

### Connections from an earlier Pharos version

Connections created by an earlier Pharos version, such as Pharos 1.x, carry over when you upgrade and keep working. Pharos refreshes and re-authorizes them through the connected-app settings that version stored, so you don't need to do anything.

If those settings are gone, or Salesforce no longer accepts that app, Pharos can't authenticate the connection. The hourly token refresh marks it **Connection invalid** and writes a log whose Summary reads: *"Connected Org was created by an earlier Pharos version and can no longer be authenticated. Delete this connection in Pharos Connected Orgs and set it up again."* **Login to Org** on that connection either shows this message as an error or fails with Salesforce's own sign-in error. **Reset** and **Login to Org** can't repair it.

Delete the connection and create it again. The steps depend on the connection:

* **The org's own (loopback) connection.** Pharos logs the message once and clears the connection's stored token, so Pharos Admin keeps working on your own session. Pharos needs this connection to attribute logs to the right org, so recreate it right away. Delete it in **Connected Orgs**. Log in as the Pharos running user first (see [Running User](https://docs.pharos.ai/configuration-guide/quick-start.md#running-user)), then open **Pharos Admin → Quick Start**, choose **Fresh Install**, click **Launch**, and work through the wizard. See [Quick Start](https://docs.pharos.ai/configuration-guide/quick-start.md).
* **A connection to another org.** Pharos retries the token refresh every hour and logs the message each time until you recreate the connection. The connection is set up on both orgs, so delete its record on both, then set it up again in the usual order (see [Source and Target](#source-and-target)). Logs written while it's invalid stay on the source: they aren't sent to the target afterwards.

{% hint style="success" %}
**Next Step:** Configure [Integrations](https://docs.pharos.ai/configuration-guide/integrations.md) to connect Pharos with your external tools (Jira, Slack, Teams, and more).
{% endhint %}
