# API Authentication

The Onboarded™ application requires authentication credentials to communicate securely with the Onboarded™ API. There are two parts to authentication that an admin in the subscriber org must complete:

1. **Authorize the Onboarded Webhook External Client App** — designate which users in your org are permitted to act as the authorized user for inbound webhook callbacks from Onboarded™.
2. **Configure OAuth Authentication** — enter your Client ID and complete the OAuth handshake so Salesforce can call the Onboarded™ API.


Complete these steps in order — OAuth will not connect successfully until the External Client App has an authorized user designated.

## Webhook External Client App Authorization

The managed package ships with an **External Client App (ECA)** named **Onboarded Webhook ECA**. Onboarded™ uses this ECA to deliver webhook callbacks back into your Salesforce org (for example, when an employee completes onboarding tasks or when Onboarded™ needs to notify your org of a record update). Before this ECA can be used, an admin in the subscriber org must designate which users are permitted to authorize it.

1. **Open External Client App Manager.** In Salesforce, navigate to **Setup** → **App Manager** (or search Quick Find for **External Client App Manager**). Locate the **Onboarded Webhook ECA** entry in the list.
2. **Open the ECA's Policies.** Click the row-level action menu next to **Onboarded Webhook ECA** and select **View**. On the detail page, open the **Policies** tab and click **Edit**.
3. **Set Permitted Users to "Admin approved users are pre-authorized".** Under **OAuth Policies**, change **Permitted Users** to **Admin approved users are pre-authorized**. Save the policy. This tells Salesforce that only users you explicitly authorize — via a permission set or profile assignment — may act as the authorized user for the Onboarded Webhook ECA.
4. **Assign the Authorized User via a Permission Set or Profile.** On the same ECA detail page, scroll to **Permission Sets** (or **Profiles**) and assign the permission set or profile whose members should be authorized to use the Onboarded Webhook ECA. The user who will configure OAuth (in the next subsection) must be a member of that permission set or profile.


> **Known Salesforce Issue (as of Summer '26):** There is a current Salesforce platform bug that prevents admins in the subscriber org from assigning the Authorized User policy of the **Onboarded Webhook ECA** to a permission set that is included *inside* the Onboarded™ managed package (for example, `Onboarded™ Admin` or `Onboarded™ HR Representative`). Until Salesforce resolves this issue, use the workaround below.


> **Workaround:** Assign the Authorized User to a permission set *or* profile in *your* org — that is, any permission set or profile that is **not** part of the Onboarded™ managed package. This can be a standard Salesforce permission set, a custom permission set you create in your org, or a user profile you control. The user who configures OAuth in the next subsection must then be a member of that permission set or assigned that profile, in addition to having the packaged **Onboarded™ Admin** permission set assigned for runtime access.


> **Skipping this step:** If the External Client App does not have an authorized user designated, the OAuth connection step that follows will fail and webhook callbacks from Onboarded™ will be rejected by Salesforce. Always complete this step before clicking **Connect to Production** or **Connect to Staging**.


## OAuth Authentication Configuration

1. **Open Onboarded™ Setup.** Navigate to the **Onboarded™ Setup** tab in your Salesforce org (requires Onboarded™ Admin permission set).
2. **Enter Client ID.** In the **Integration Settings** > **Authenticate** section:
  - If not already configured, click **Configure** to enter your credentials
  - If already configured, click **Edit** to modify your credentials
| Field | Source |
|  --- | --- |
| Client ID | Found in your Onboarded™ Account Settings (Settings > Account > Edit Account) |
3. **Save and Connect.**
  1. Click **Save Credentials** to store the Client ID securely
  2. Click **Connect to Production** (or **Connect to Staging** for test environments) to initiate the OAuth authorization flow
  3. A popup window will open — log into your Onboarded account to authorize the connection
  4. Once authorized, the status will show as "Connected"


> **Note:** The environment (Production or Staging) is determined by the installed package and cannot be changed. Production packages connect to the Onboarded production environment, while QA/test packages connect to the staging environment.


> **Security Note:** The user configuring authentication will be used for API calls. Ensure this user has appropriate access to all Salesforce objects and fields that need to be synchronized. See the Security Overview page for more details.