Connected App Management

The OAuth app is a critical component of aprity's security model. It enables the JWT Bearer authentication flow that allows aprity to securely access your Salesforce org's metadata without storing user credentials, and it also powers the OAuth (Authorization Code + PKCE) login used by the aprity web portal.

:::note Salesforce now calls it an External Client App Salesforce now steers admins to create an External Client App (ECA) rather than the legacy Connected App. The two are functionally equivalent for aprity, and the same app serves both the backend JWT Bearer flow and the web portal SSO login.

The two are managed in different places, and the UI differs:

You created	Manage it in
External Client App (current)	Setup > External Client App Manager -- use the app's row actions menu to Modify Settings or Modify Policies
Connected App (legacy)	Setup > App Manager and Setup > Manage Connected Apps

This page uses "Connected App" in prose for continuity, but where the navigation differs the ECA path is called out explicitly. If you followed the Setup Guide, you have an External Client App. :::

This guide covers ongoing management tasks for the app after initial setup. For the step-by-step creation process, see Configuring JWT Bearer Authentication.

Connected App Components

The aprity Connected App consists of three key elements:

Component	Purpose	Location (External Client App)
Digital certificate	Public key used to verify JWT tokens signed by aprity	Settings > OAuth Settings > Flow Enablement
Consumer Key	Unique identifier for the app	Settings > OAuth Settings > App Settings
OAuth scopes	Permissions granted to aprity	Settings > OAuth Settings > OAuth Scopes
Permitted Users	Who may authenticate through the app	Policies > OAuth Policies > Plugin Policies
Selected Profiles	Pre-authorized profiles (incl. the integration user)	Policies > App Policies (visible once Permitted Users is set)

Required OAuth Scopes

The backend metadata connection requires exactly two OAuth scopes:

• Manage user data via APIs (api) -- Allows aprity to read metadata through the Salesforce API.
• Perform requests at any time (refresh_token, offline_access) -- Allows authentication without user interaction.

If you also enable the aprity web portal or the Remote MCP server (AI clients such as Claude, ChatGPT or Cursor), the same app needs two more:

• Access the identity URL service (id, profile, email, address, phone) -- Identifies the signing-in user.
• Access unique user identifiers (openid) -- OpenID Connect subject claim.

:::caution Match the label, not the scope code In External Client Apps, openid is the code behind "Access unique user identifiers", not behind "Access the identity URL service". There is no standalone "Access basic information (email)" entry -- email and profile ride along in the identity URL scope. Selecting by scope code will send you to the wrong row. :::

:::info Minimal access aprity only reads metadata. It does not create, update, or delete records in your org. The api scope is the minimum required for metadata access. The two portal scopes are identity-only -- they grant no data access. :::

Callback URLs

Each aprity browser flow redirects back to its own URL. The Callback URL field accepts several, one per line — add the ones you use:

Surface	Callback URL to add
Web portal	the portal callback shown in your aprity setup screen
Remote MCP server (AI clients)	https://mcp.aprity.ai/v1/mcp/oauth/sf-callback

:::caution MCP uses the same app, on purpose The AI clients connect through this Connected App, not an aprity-owned one. Your org's login policy applies, the users who can connect are the ones you pre-authorize below, and disabling this app cuts off aprity's MCP access in one action. :::

:::info Who can connect an AI client Because aprity requires Admin approved users are pre-authorized (see below), only users of a selected profile or permission set can connect. A user outside them gets the Salesforce error user hasn't approved this consumer, which does not say what to do — so tell your users which profiles are covered. :::

Locating the Consumer Key

External Client App:

1. Go to Setup > External Client App Manager.
2. Locate aprity, open the row actions menu at the far right, and select Modify Settings.
3. Expand OAuth Settings.
4. In the App Settings block, click Consumer Key and Secret.
5. Complete the identity verification if prompted (emailed code).
6. Copy the Consumer Key.

Legacy Connected App:

1. Go to Setup > App Manager.
2. Find aprity, click the dropdown arrow, select View.
3. Click Manage Consumer Details in the API section.
4. Complete the identity verification if prompted.

warning

Do not share the Consumer Secret. The JWT Bearer flow does not use the Consumer Secret, and exposing it introduces unnecessary risk.

Managing Pre-Authorization

Depending on your org's security policies, you may need to pre-authorize the Connected App for specific users or profiles.

Check current policy

External Client App: open Setup > External Client App Manager, locate aprity, open the row actions menu at the far right, then select Modify Policies. In the policy editor, use OAuth Policies > Plugin Policies > Permitted Users.

Legacy Connected App: Setup > Connected Apps > Manage Connected Apps > aprity, then review Permitted Users under OAuth Policies.

Pre-authorization options

Setting	Behavior
All users can self-authorize	Any user with the correct permission set can use the app. Salesforce prompts for consent on first use.
Admin approved users are pre-authorized	Only users in explicitly assigned Profiles or Permission Sets can use the app. No consent prompt.

aprity requires Admin approved users are pre-authorized -- JWT Bearer has no browser session in which a consent prompt could be answered, so a self-authorize app fails verification with "user hasn't approved this consumer".

:::info The picker appears only after you set the policy Changing Permitted Users is what reveals the Select Profiles and Select Permission Sets pickers under App Policies. Before that, App Policies shows only a Start Page field. Set the policy first, confirm the "Confirm permitted user policy" dialog, then assign the profile. :::

Assign the integration user's profile under Select Profiles -- the profile that user actually has in Setup > Users, which is frequently a custom profile rather than the standard System Administrator. Managed-package permission sets such as aprity Admin appear in the adjacent Select Permission Sets list but have been observed to be rejected on save (state=MANAGED_INSTALLED) -- assign those to users directly via Setup > Permission Sets instead.

Certificate Management

The digital certificate uploaded to the Connected App has an expiration date. When the certificate expires, aprity can no longer authenticate to your org.

Checking certificate expiration

The certificate expiration date is not directly visible in the Connected App UI. To check:

1. Open the .crt file you originally downloaded from aprity.
2. Use a certificate viewer or run the following command (on macOS/Linux):

   openssl x509 -in aprity.crt -noout -enddate

3. Alternatively, check the aprity Settings tab, which displays the certificate validity period.

Rotating the certificate

When a certificate is approaching expiration, follow the Certificate Rotation Guide for step-by-step instructions on downloading a new certificate and uploading it to the Connected App.

Modifying the Connected App

Adding or removing OAuth scopes

If you accidentally removed a required scope or need to verify the configuration:

1. Go to Setup > External Client App Manager, locate aprity, open its row actions menu, and select Modify Settings.
2. Click Edit and expand OAuth Settings.
3. Check the Selected OAuth Scopes list against Required OAuth Scopes above.
4. Click Save.

The same screen holds the Callback URL, Flow Enablement (JWT Bearer + certificate) and Security toggles. Policies are opened separately from the manager list through the Modify Policies row action.

caution

After modifying OAuth settings, Salesforce may take 2 to 10 minutes to propagate changes. Test the connection from the aprity Settings tab after waiting.

Revoking access

To temporarily disable aprity's access to your org:

External Client App: open Setup > External Client App Manager, locate aprity, open its row actions menu, and select Disable. Use the same menu to Enable it again.

Legacy Connected App: Setup > Connected Apps > Manage Connected Apps > aprity, then Block / Unblock.

Either way, in-flight aprity scans will fail until access is restored.

Troubleshooting

Issue	Cause	Solution
"invalid_grant" error	Certificate mismatch or expired certificate	Re-download and re-upload the certificate. See Certificate Rotation.
"user hasn't approved this consumer"	Connected App not pre-authorized for the user	Add the user's profile or permission set to the pre-authorized list.
Connection test fails after 2+ minutes	OAuth scopes missing	Verify both api and refresh_token, offline_access scopes are selected.

For additional troubleshooting, see JWT Verification Fails.