---
title: "Connected App"
slug: "connected-app"
tags: ["sfdc", "setup"]
updated: 2026-09-01T10:46:08Z
published: 2026-09-01T10:46:08Z
canonical: "docs.relaynetwork.com/connected-app"
excludeFromExternalSearch: true
---

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

# Connected App

> [!WARNING]
> Salesforce is deprecating Connected Apps
> 
> Salesforce Connected Apps are now off-by-default and are being phased out in favor of [**External Client Apps (ECA)**](/v1/docs/connected-app#2-salesforce-create-the-relay-connected-app). If your org's security review has flagged the Legacy OAuth Username-Password flow, skip to [Migrating to an External Client App (ECA)] below.

## Overview

A Salesforce Connected App configuration requires setup on the Relay side (the push API) and the Salesforce side (receiver).

1. [Configure a Relay Push API within the CXB Portal](/v1/docs/connected-app#1-relay-configure-the-push-api-in-cx-builder)
  1. A certification will be created and downloaded. This certification will be required when configuring the Connected App in Salesforce
2. Configure the Salesforce side— choose ONE of the following:
  1. [**External Client App (ECA)— Recommended**](/v1/docs/connected-app#2-salesforce-create-the-relay-connected-app)
  2. [Connected App (Legacy- being deprecated)](/v1/docs/connected-app#3-salesforce-create-the-relay-connected-app-legacy)
3. [Edit the Push API configuration (from step 1) in the Relay CXB](/v1/docs/connected-app#3-relay-update-relay-push-api-configuration)
  1. Update the *Salesforce Consume Key* with the value (from step 2).

## 1. Relay - Configure the Push API in CX Builder

> [!WARNING]
> IMPORTANT
> 
> If you do not see the API Management module on the left menu, please check that you have either Client Admin or Client User with Integration Permissions in the System.

[Video](https://cdn.us.document360.io/6738087b-455d-402f-b70a-a44a4231547e/Images/Documentation/SFDC%20Installation%20-%20CX%20Builder_%20Adding%20Push%20Events%20to%20CX%20Builder.mp4)

1. Login to the Relay CXB Portal
2. Click on **API Management** in the left menu column.
3. Click on the **Push API Integration** tab. This is the “home page” of the Push API Integration UI, where you will see a list of existing integrations - if any exist.

![](https://cdn.us.document360.io/6738087b-455d-402f-b70a-a44a4231547e/Images/Documentation/image-20230614-162955.png)

1. Click the “**ADD INTEGRATION**” button. A modal will pop up with a dropdown menu.
  1. If you are installing the managed package from the App exchange, choose **Salesforce App Exchange Package**. If your Relay CSM provided you a link to the unmanaged package, select **Salesforce Unmanaged Package**.

![](https://cdn.us.document360.io/6738087b-455d-402f-b70a-a44a4231547e/Images/Documentation/Screenshot 2025-06-04 at 10.07.23 AM(1).png)
2. Fill out the configuration dialog:

**Name**: This is the name of the integration you are creating, and can be named whatever you wish to refer to it as.

**Version**: Select the version of this integration form with which you wish to integrate your client. The latest version is selected by default

**Salesforce Username**: This is the Salesforce username that the Client associated with the Connected App. For now, add any value in this box, later on in the setup you will obtain this value and we will update it

> [!NOTE]
> Salesforce Subdomain:
> 
> - For Salesforce sandboxes, set the value to **Test**
> - For Salesforce production, developer orgs or personal accounts, set the value to:
>   - **Login -** If your company uses the generic endpoint login.salesforce.com
>   - **My Domain -** If your company's org runs on Hyperforce infrastructure, which requires a My Domain URL (if chosen, a field to enter the custom domain will appear)

![](https://cdn.us.document360.io/6738087b-455d-402f-b70a-a44a4231547e/Images/Documentation/Screenshot 2026-08-31 at 2.05.18 PM.png)

**Salesforce Consumer Key**: This is the Salesforce Consumer Key of the Connected App Configuration. *For now, add any value in this box, later on in the setup you will obtain this value and we will update it*.

**Event Set**: This is the standard set of event types that will be inserted as records into the following objects: [RelayEvents__c](/v1/docs/relayevents-c) and [RelayPowerups__c](/v1/docs/relaypowerups-c).
3. Download the Certificate: The certificate/cert (or `public_key`) will appear after you click **Activate**. A modal will appear, click on **You can download it here**. If you need to access it after this modal is closed, the .crt file can be downloaded at any time when clicking on the edit icon setup, and locating the **You can download it here** at the bottom of the modal.
  1. Provide the downloaded public certificate to the Salesforce admin who is installing the Relay Package.

![](https://cdn.us.document360.io/6738087b-455d-402f-b70a-a44a4231547e/Images/Documentation/Screenshot 2025-08-08 at 3.45.45 PM(1).png)

## 2. **External Client App (ECA)** setup

A Salesforce ECA configuration requires setup on the Relay side (the push API) and the Salesforce side (receiver) — the same two-sided pattern as the Connected App above.

1. Follow Salesforce's guide to create a local External Client App: [Create a Local External Client App](https://help.salesforce.com/s/articleView?id=xcloud.create_a_local_external_client_app.htm&type=5)
2. Set up the ECA using the values below.
3. Update the Push API configuration in the Relay CXB Portal with the new Consumer Key (same as Section 3 above).

### ECA Configuration

- Set *ECA Name* to **Relay Connected App**.
- Set *API Name* to **Relay_Connected_App**.
- Set *Contact Email* to the email address that will receive any errors related to this Connected App.

### OAuth Settings

![](https://cdn.us.document360.io/6738087b-455d-402f-b70a-a44a4231547e/Images/Documentation/eca-oauth-settings-and-flow-enablement.png)

Figure A.

- Set the *Callback URL* to [**https://localhost**](https://localhost).
- Under **OAuth Scopes**, move the following to **Selected OAuth Scopes**:
  - Manage user data via APIs (api)
  - Full access (full)
  - Perform requests at any time (refresh_token, offline_access)
- Under **Flow Enablement**, check **Enable JWT Bearer Flow** and upload the certificate provided by your Relay Implementation Manager.

### OAuth Security Configuration

![](https://cdn.us.document360.io/6738087b-455d-402f-b70a-a44a4231547e/Images/Documentation/eca-oauth-security-configuration.png)

Figure B.

- Check **Require secret for Web Server Flow**
- Check **Require secret for Refresh Token Flow**
- Check **Require Proof Key for Code Exchange (PKCE) extension for Supported Authorization Flows**
- Leave all other settings at their default values, then click **Save**.

> [!CAUTION]
> **STOP**
> 
> You need to add the Salesforce Username and Consumer Key of the ECA in CX Builder.
> 
> - Under **App Settings**, click **Consumer Key and Secret** to reveal the values. Save the Consumer Key — it goes on the Relay Portal.
> 
> ![](https://cdn.us.document360.io/6738087b-455d-402f-b70a-a44a4231547e/Images/Documentation/eca-consumer-key-and-secret.png)
> 
> Figure C.
> 
> - In CX Builder, edit the Push API connection and enter the Salesforce Username and Consumer Key.

### Update the ECA Policies

**App Policies:**

![](https://cdn.us.document360.io/6738087b-455d-402f-b70a-a44a4231547e/Images/Documentation/eca-app-policies-configuration.png)

Figure D.

- Under **Select Permission Sets**, move **Relay Network Connected App** and **Relay Network Connected App Staging** to *Selected Permission Sets*.
- Click **Save**.

**OAuth Policies:**

![](https://cdn.us.document360.io/6738087b-455d-402f-b70a-a44a4231547e/Images/Documentation/eca-oauth-policies-configuration.png)

Figure E.

- Set *Permitted Users* to **Admin approved users are pre-authorized**.
- Set *IP Relaxation* to **Relax IP Restrictions**.
- Leave all other settings (including the 365-day Refresh Token Policy) at their defaults, then click **Save**.

You should now have a properly configured **Relay External Client App**, ready for the Consumer Key to be added to the Push API configuration in Section 3 above.

## 4. Salesforce - Create the Relay Connected App (Legacy)

> [!CAUTION]
> Legacy Path
> 
> This section applies to orgs that have not yet migrated to an External Client App. New installs should use [Section 2 — External Client App (ECA)](/v1/docs/connected-app#2-salesforce-create-the-relay-connected-app) instead.

The **Connected App** allows Relay Network to insert event data, occurring within the Relay Network, into your Salesforce org. Based on the Relay event type, a record will be inserted into one of the two following objects: [RelayEvents__c](/v1/docs/relayevents-c) or [RelayPowerups__c](/v1/docs/relaypowerups-c).

> [!WARNING]
> IMPORTANT
> 
> If a setting is not specifically called out in the the below article, leave it set to the default value.

[Video](https://cdn.us.document360.io/6738087b-455d-402f-b70a-a44a4231547e/Images/Documentation/SFDC%20Installation%20-%20Connected%20App_%20Relay%20Connected%20App%20(1).mp4)

1. As an admin, login to your Salesforce org.
2. Access your org’s **Setup** page.
3. Navigate to **PLATFORM TOOLS → Apps → App Manager**
4. Click the **New Connected App** button

![rn-sfdc-new_connected_app](https://cdn.us.document360.io/6738087b-455d-402f-b70a-a44a4231547e/Images/Documentation/rn-sfdc-new_connected_app.png)

Figure 1.

1. Fill out the Managed Connect App as outlined below

![rn-sfdc-connected_app](https://cdn.us.document360.io/6738087b-455d-402f-b70a-a44a4231547e/Images/Documentation/rn-sfdc-connected_app.png)

Figure 2.

### Basic Information (1)

- Set *Connected App Name* to **Relay Connected App**.
- Set *API Name* to **Relay_Connected_App**.
- Set *Contact Email* to the email address that will receive and errors related to this Connected App.

### API (Enable OAuth Settings)

- Check **Enable OAuth Setting** (2)
- Uncheck **Enable for Device Flow**
- Because this connected app is for connecting to the Relay system, no login user interface is required. Therefore, you can set the *Callback URL* to **https://localhost**
- Check **Use Digital Signatures** **(3)**
  - Click the **Choose File** button. Select the certificate file that was provided to you by your Relay Implementation Manager.
- Move the following to the **Selected OAuth Scopes** **(4)**
  - Manage User Data via APIs (api)
  - Perform requests at any time (refresh token, offline access)
- Check the following options (5)
  - Require Proof Key for Code Exchanges (PKCE). Extension for Supported Authorizer Flows
  - Require Secret for Web Server Flows
  - Require Secret for Refresh Token Flows
- Click **Save**
- You should receive a message that it can take up to 10 mins for changes to take effect. Click **Continue.**

> [!CAUTION]
> STOP
> 
> You need to add the Connected App Username and Consumer Key of the Connected App in CX Builder.
> 
> - Click the **Manage Consumer Details** button. This should open a new tab in your browser.
> - In CX Builder, edit the Push API connection you created in the first step on this page, and add in the appropriate details.
> - Return to the original browser tab with the *Managed Connected App* settings you just created.

### Update the Connected App Policies

[Video](https://cdn.us.document360.io/6738087b-455d-402f-b70a-a44a4231547e/Images/Documentation/SFDC%20Installation%20-%20Connected%20App_%20Relay%20Connected%20App%20Policies.mp4)

- You should still be on the Connected App settings page, so click the **Manage** button. If you are not on the Relay Connected App settings page follow the below steps:
  - From setup, navigate back to *PLATFORM TOOLS → Apps → App Manager*
  - Locate the **Relay Connected App** you just created
  - Click the drown down arrow and select **Manage**
- Click the **Edit Policies** button

![rn-sfdc-connected-app-edit-policies](https://cdn.us.document360.io/6738087b-455d-402f-b70a-a44a4231547e/Images/Documentation/rn-sfdc-connected-app-edit-policies.png)

Figure 3.

### Relay Connected App Policies

![rn-sfdc-connected-app-policies](https://cdn.us.document360.io/6738087b-455d-402f-b70a-a44a4231547e/Images/Documentation/rn-sfdc-connected-app-policies.png)

Figure 4.

#### OAuth Policies

- Set *Permitted Users* to **Admin approved users are pre-authorized**
- Set *IP Relaxation* to **Relax IP Restrictions.**
- Leave all other settings at their default values.
- Click **Save** to return to the **Relay Connected App** detail page

### Relay Connected App Permission Sets

- Locate the *Permission Sets* section and click the **Manage Permission Sets** button.

![rn-sfdc-connected-app-manage_permission_sets](https://cdn.us.document360.io/6738087b-455d-402f-b70a-a44a4231547e/Images/Documentation/rn-sfdc-connected-app-manage_permission_sets.png)

Figure 5.

#### Application Permission Set Assignment

![rn-sfdc-connected_app-permission-set-assignment](https://cdn.us.document360.io/6738087b-455d-402f-b70a-a44a4231547e/Images/Documentation/rn-sfdc-connected_app-permission-set-assignment.png)

Figure 6.

- Locate the **Relay Network Connected App** permission set, you previously created in the [Permission Sets](/v1/docs/configure-permissions) article, and check it.
- Click the **Save** button.

You should not have a properly configured **Relay Network Connected App.**

## 3. Relay - Update Relay Push API Configuration

- Navigate back the Relay CXB Portal
- Edit the *Push API* configuration you created in the first step
- Copy the **Consumer Key** to the *Salesforce Consumer Key* field of the push API configuration
- Save

---

## Locating Common Settings

> [!NOTE]
> NOTE
> 
> All of the below settings can ebe accessed from the App Manager drop-down menu.
> 
> PALTFORM TOOLS → Apps → App Manager → (Locate Relay Connected App) → Drop-down menu (located on the far right)

| Setting | Location |
| --- | --- |
| - Consumer Key | From the drop-down menu select **View** → **Manage Consumer Details** |
| - OAuth certificate - OAuth Scopes | From the drop-down menu select **Edit** |
| - Permission Set | From the drop-down menu select **Manage →** scroll down to the *Permission Set* section |

## Troubleshooting

The section covers common errors related to the Connected App configuration and possible root causes.

| Error | Error Description | Possible Cause |
| --- | --- | --- |
| invalid_client | invalid client credentials | The uploaded OAuth .crt file is incorrect. Please replace the certificate. |
| invalid_client_id | client identifier invalid | The consumer key is incorrect. Please verify the correct consumer key has been provided to Relay. |
| invalid_grant | user hasn’t approved this consumer | The provided user name does not have permissions to the connected app. - Verify the **OAuth Policies** configuration. - Verify the **Permission Set Assignment** and that the provided user is in the permission set. - Verify the Relay CXB Push API Configuration is using the Salesforce **username** value and *not* the email address. Note, the **username** often looks like an email address but it is not. |
| invalid_grant | refresh_token scope is required and the connected app should be installed and preauthorized. | Verify your **OAuth Scopes** are properly configured (Figure 2. #4). |

Every client will have a Relay Client Success Manager (CSM) assigned to the account. This person will be your primary point of contact for the duration of your engagement with Relay Network.