Managing the External Client App

aprity connects to your org through one External Client App that you create in Salesforce during setup. The same app serves three purposes:

Purpose	How it works
Analyses	The aprity service reads your metadata with the OAuth 2.0 JWT Bearer flow, using the certificate you uploaded.
Web portal sign-in	Readers sign in to the portal with their Salesforce login (OAuth authorization code with PKCE).
AI clients (Remote MCP)	ChatGPT, Claude, Cursor or GitHub Copilot users sign in with their Salesforce login through this app.

The aprity setup wizard (the aprity tab, before the org is connected) walks you through creating it. This page covers what to check and change afterwards. For the first-time procedure, see Configuring JWT Bearer Authentication.

Older installations

Salesforce now steers admins to External Client Apps. If your org was set up earlier with a legacy Connected App, the settings are the same; you manage it from Setup > App Manager and Setup > Manage Connected Apps instead of the External Client App Manager.

Where to find it

1. Go to Setup > External Client App Manager.
2. Find the aprity app and open the row actions menu at the far right.
3. Choose Modify Settings (OAuth settings, callback URLs, certificate) or Modify Policies (who can use the app).

Settings

OAuth scopes

Scope (exact label in Salesforce)	Needed for
Manage user data via APIs (api)	Analyses
Perform requests at any time (refresh_token, offline_access)	Analyses
Access the identity URL service (id, profile, email, address, phone)	Portal and AI clients
Access unique user identifiers (openid)	Portal and AI clients

Match the label, not the scope code

In External Client Apps, openid sits behind Access unique user identifiers, not behind Access the identity URL service. There is no separate "email" scope: email and profile come with the identity URL service.

aprity reads metadata only. It does not create, update or delete records in your org. The two identity scopes grant no data access.

Callback URLs

The Callback URL field takes one URL per line. The setup wizard shows the exact list for your environment. For the default environment:

https://login.salesforce.com/services/oauth2/callback
https://api.aprity.ai/v1/portal/auth/sf/callback
https://mcp.aprity.ai/v1/mcp/oauth/sf-callback

The second line is required for the web portal, the third for AI clients. A missing line shows up as a Salesforce redirect_uri_mismatch page when someone signs in.

Flow enablement and certificate

• Enable JWT Bearer Flow must be checked, with the aprity certificate uploaded. See Certificate Rotation.

Security

• Require Proof Key for Code Exchange (PKCE) stays checked.
• If you use the web portal, uncheck Require secret for Web Server Flow and Require secret for Refresh Token Flow. The portal is a public client secured by PKCE; if a secret stays required, portal sign-in fails. This does not affect analyses, which use the certificate.

Consumer Key

aprity needs the Consumer Key only, entered once in the setup wizard. It never uses the Consumer Secret: do not share the secret.

To view it: Modify Settings > OAuth Settings > App Settings > Consumer Key and Secret. Salesforce may ask you to verify your identity first.

Policies

Who can sign in

In Modify Policies > OAuth Policies > Plugin Policies, Permitted Users must be Admin approved users are pre-authorized. The JWT Bearer flow has no browser in which a user could approve the app, so a "self-authorize" app fails with user hasn't approved this consumer.

Once that is set, App Policies shows a Select Profiles picker. Select:

• the profile of the integration user that aprity uses to read metadata (check it in Setup > Users; it is often a custom profile, not System Administrator);
• the profiles of everyone who will sign in to the web portal or connect an AI client.

Adding a profile here does not give portal access by itself: users also need the aprity User or aprity Admin permission set. See Permission Sets Explained.

Use profiles, not permission sets

The Select Permission Sets picker next to it may refuse the aprity permission sets because they belong to a managed package. Use Select Profiles here, and assign the aprity permission sets to users directly.

A user whose profile is not selected gets user hasn't approved this consumer when signing in to the portal or connecting an AI client. Tell your users which profiles are covered.

IP relaxation

In OAuth Policies > App Authorization, set IP Relaxation to Relax IP restrictions, as the setup wizard instructs.

Salesforce can take a few minutes to apply changes to the app. Wait before testing again.

Revoking access

To suspend all aprity access to your org:

• External Client App: in Setup > External Client App Manager, open the aprity row actions menu and disable the app. Enable it again the same way.
• Legacy Connected App: Setup > Manage Connected Apps > aprity, then block it.

While the app is disabled, analyses cannot read metadata, portal sign-in fails, and AI clients lose access.

Troubleshooting

Symptom	Likely cause	What to do
invalid_grant during verification or an analysis	Certificate missing or different from aprity's current one	Upload the certificate again. See Certificate Rotation.
user hasn't approved this consumer	The user's profile is not selected in the app policies	Add the profile under Select Profiles.
redirect_uri_mismatch at sign-in	A callback URL is missing	Add the missing line to Callback URL.
Portal sign-in fails after the Salesforce login	A client secret is still required, or no aprity permission set	Uncheck the two "Require secret" options; check the user's permission sets.

See also JWT Verification Fails, Portal Login Fails and MCP Authentication Failed.